skip to content

In Cypress, what does DEBUG=cypress:* print, and how do you narrow it down?

level: seniorimportance: should knowfreq 42%

answer

  1. An environment variable, not a config key
  2. It instruments Cypress, not your app
  3. Package, then module, then everything
  4. Commas combine, a minus subtracts
  5. DEBUG_DEPTH for nested objects

basics

~20 s

It streams the internal logs of Cypress's own Node-side packages to the terminal — argument parsing, project opening, browser launch, spec bundling, network interception — not your application. Narrow it by naming a package or module, combining namespaces with commas, and excluding one with a leading minus.

solid answer

~40 s

Cypress is built on the `debug` npm module, so setting the system environment variable `DEBUG` before `cypress run` or `cypress open` turns on its internal logging. What you get is **Cypress's own machinery** — how the CLI parsed your arguments, how it located the project and its specs, which browsers it found and launched, spec bundling, the interception layer, video, fixtures — which is exactly what you want when the run never reaches a test and the Command Log has nothing to show. `cypress:*` is everything and is a firehose, so narrow it: `cypress:server` for a few top-level messages, `cypress:server*` for the whole package, `cypress:server:project` for one module. Combine namespaces with commas and drop one with a leading `-`, as in `DEBUG=cypress:server*,-cypress:server:browsers*`. `DEBUG_DEPTH=3` stops nested objects printing as `[Object]`.

code

bash · 9 lines
bash
# the run never reaches a spec: watch argument parsing and spec discovery
DEBUG=cypress:cli,cypress:server:args,cypress:data-context:sources:* \
  npx cypress run --spec 'cypress/e2e/ticket-queue.cy.js'

# the browser will not start: browser discovery plus launch, nothing else
DEBUG=cypress:server:browsers*,cypress:launcher:* npx cypress run

# whole server package minus the browser noise, with nested objects expanded
DEBUG=cypress:server*,-cypress:server:browsers* DEBUG_DEPTH=3 npx cypress run

go deeper

for a junior

Know that DEBUG is a system environment variable set before the cypress command, and that it prints Cypress's own internal logs rather than anything from your application.

for a middle

Explain the namespace shape — package, package wildcard, single module — and how commas combine namespaces while a leading minus removes one.

for a senior

An interviewer expects a diagnosis path: which namespace you reach for when the browser will not launch, when a spec will not compile, and when a run never finds its specs, plus why you start narrow.

for a principal

Own the cost side: debug capture is heavy and slows runs, and its output is undocumented internal chatter, so decide when it is worth turning on in a pipeline and how such captures are shared.

## What the variable actually turns on Cypress uses the `debug` npm module internally, and every package it is built from writes under its own namespace: the CLI, the server, the launcher, the data layer, the network and net-stubbing layers, the webpack preprocessor, and the driver that runs in the browser. Setting the operating-system environment variable `DEBUG` before you start Cypress makes the matching namespaces print to the terminal. ```bash DEBUG=cypress:* npx cypress run ``` The crucial framing: this is **instrumentation of Cypress, not of your application or your test**. It will not tell you why an assertion failed — the Command Log already does that far better. It tells you what Cypress itself did: which arguments it parsed out of your command line, which config file it resolved, which spec files matched your pattern, which browser binaries it found on the machine, how it launched one, how it bundled the spec, what the interception layer did with a request. That is the class of failure where the browser is not the problem and there is nothing to look at in open mode, because the run died before a test ran. ## Narrowing, combining and excluding `cypress:*` on a real suite generates an enormous amount of output and measurably slows the run, so treating it as the default is a mistake. There are three levels of granularity: ```bash DEBUG=cypress:server ... # a few top-level messages DEBUG=cypress:server* ... # every message from the server package DEBUG=cypress:server:project ... # one module inside it ``` Namespaces combine with commas, and a leading `-` excludes one: ```bash # spec discovery, without everything else DEBUG=cypress:cli,cypress:data-context:sources:* npx cypress run # the whole server package, minus the noisy browser chatter DEBUG=cypress:server*,-cypress:server:browsers* npx cypress run ``` ## Namespaces worth knowing by name | Set `DEBUG` to | To investigate | |---|---| | `cypress:cli*` | command-line parsing and binary installation | | `cypress:server:args` | arguments not being parsed the way you meant | | `cypress:data-context:sources:*` | Cypress not finding the project data you expect | | `cypress:server:project` | opening the project | | `cypress:server:browsers*` | which browsers were found | | `cypress:launcher:*` | launching the browser it found | | `cypress:server:preprocessor` / `cypress:webpack` | specs failing to compile or bundle | | `cypress:net-stubbing:*` / `cypress:network:*` | the interception layer | | `cypress:server:task` | a `cy.task()` that is not behaving | | `cypress:server:video` | video recording | | `cypress:server:fixture` | fixture files not loading | ## Two adjacent switches - **`DEBUG_DEPTH`.** Deeply nested objects print as `[Object]` by default. `DEBUG=cypress:server:socket-base DEBUG_DEPTH=3` expands them, which is the difference between seeing `body: [Object]` and seeing what was actually sent. - **`NODE_DEBUG`.** Some third-party modules bundled with Cypress, such as `@cypress/request`, log under Node's own variable instead, so combining the two — `DEBUG=cypress:net-stubbing:server:intercept-request NODE_DEBUG=request` — is sometimes what it takes to see a request end to end. ## Turning it on in the browser The namespaces above are Node-side. During `cypress open` you can also switch on the driver package's logs inside the browser, from the DevTools console: ```javascript localStorage.debug = 'cypress*' // and to turn it back off delete localStorage.debug ``` Reload, set the console's level to Verbose, and you get the `cypress:driver` messages. You will not see server-side namespaces there — the two halves log to different places, and that split is the first thing to keep straight when someone says "I turned on DEBUG and saw nothing". ## Operating it sanely 1. **Reproduce the failure first**, then re-run the exact same command with `DEBUG` set. Turning it on speculatively across a whole suite buys noise. 2. **Start narrow.** Pick the namespace for the phase that failed — `cypress:server:args` if the CLI seems to be ignoring a flag, `cypress:server:browsers*` and `cypress:launcher:*` if it cannot start a browser, `cypress:server:preprocessor` if a spec will not compile. 3. **Widen only if the narrow namespace is silent**, and use `-` to subtract what floods you rather than jumping straight back to `cypress:*`. 4. **Compress before sharing.** These captures are large; zip the file rather than pasting thousands of lines into an issue. Note also that the output is Cypress's internal chatter, written for Cypress's own maintainers. It is stable enough to read but it is not a documented contract, so treat a namespace's exact lines as a diagnostic aid rather than something to assert on.

  • Someone sets DEBUG=cypress:* and reports seeing nothing about their failing assertion. What went wrong?
    Nothing — they aimed the wrong tool. `DEBUG` instruments Cypress's own Node-side packages, so it reports argument parsing, project resolution, browser launch, bundling and interception. It has nothing to say about why `.should('have.text', ...)` failed; that lives in the Command Log and the error. Use `DEBUG` when the run dies before a test runs, or when the failure is in Cypress's plumbing rather than the page.
  • How do you get Cypress's browser-side debug output rather than the terminal's?
    Set `localStorage.debug = 'cypress*'` from the DevTools console during `cypress open`, reload, and turn the console's level up to Verbose. That surfaces the `cypress:driver` package's messages, which run in the browser rather than in Node. `delete localStorage.debug` turns it back off. The Node-side namespaces never appear there, and the driver's never appear in the terminal.

saying these in an interview costs you the question

  • Thinks DEBUG shows why an assertion failed
  • Sets DEBUG as a Cypress config key rather than an env var
  • Runs DEBUG=cypress:* routinely in CI
  • Cannot name any narrower namespace than cypress:*
  • Unaware nested objects print as [Object] without DEBUG_DEPTH