Puppeteer DEBUG logs omit page console errors when diagnosing deployment failures

No — DEBUG output alone is not sufficient. Puppeteer's DEBUG=puppeteer:* logging and the page's console output are two separate pipelines, and the DEBUG stream will never contain console.log or JavaScript errors from the page itself. For deployment-failure diagnosis you always need explicit page-level listeners; DEBUG is a supplement, not a substitute.

Why the two streams are separate

The DEBUG environment variable enables Puppeteer's own internal logging (via the debug npm package). It shows what Puppeteer is doing — launching Chrome, sending DevTools Protocol commands, waiting for selectors. Page console output travels over the Chrome DevTools Protocol as Runtime.consoleAPICalled and Runtime.exceptionThrown events, which Puppeteer surfaces only through event listeners on the Page object. Nothing bridges those events into the DEBUG log stream.

The listeners to attach

Attach them immediately after browser.newPage(), before any navigation. This is the most common silent-failure cause: listeners attached after page.goto() miss the console errors emitted during page load — often exactly the errors that explain a failed deployment.

const page = await browser.newPage();

page.on('console', msg => {
  console.log(`[page:${msg.type()}]`, msg.text());
});
page.on('pageerror', err => {
  console.error('[pageerror]', err.message);
});
page.on('requestfailed', req => {
  console.error('[requestfailed]', req.url(), req.failure()?.errorText);
});

await page.goto(deployUrl);

These three cover most deployment diagnostics: application logging, uncaught exceptions, and failed network requests (missing assets, 4xx/5xx API calls). Prefer msg.text() over serializing msg.args() — the args are JSHandles and can hang on unserializable objects.

Where DEBUG still earns its place

Use DEBUG=puppeteer:protocol alongside the listeners when you need to isolate a listener bug from a browser problem. The protocol log shows raw CDP traffic, so you can grep for Runtime.consoleAPICalled to confirm Chrome is actually emitting the events. If the events appear in the protocol log but your handler never fires, the bug is in your listener setup (usually timing). If they don't appear, the page genuinely isn't logging.

A simple decision rule

• Diagnosing why a page/deploy misbehaves → page listeners are mandatory; DEBUG is optional context.
• Diagnosing Puppeteer itself (timeouts, protocol errors, launch failures) → DEBUG is the right tool; listeners add nothing.
• Unsure which side is failing → run both and correlate.

CI and container caveats

In CI, console events can be lost if the process exits or the browser closes before async handlers flush. Await the diagnostic step explicitly and close the browser in a finally block. Also note that high-volume console logging can slow headless Chrome; filter by msg.type() (e.g., only error and warning) if noise becomes a problem.

Verify the pipeline works

1. Attach the listeners right after newPage(), reproduce the failing deployment, and confirm errors reach stdout/stderr.
2. Trigger a known error with await page.evaluate(() => console.error('test')) to prove the listener path works end-to-end.
3. Run with DEBUG=puppeteer:protocol and grep for Runtime.consoleAPICalled to confirm Chrome is emitting events.

One caveat: event names and message APIs (msg.type(), msg.text()) have shifted across Puppeteer versions, so check the typings of your installed version rather than assuming. The listener-first pattern itself, though, is stable and should be the default in any deployment-diagnosis harness.