puppeteer/puppeteer · error · Error

Missing target for DevTools page (id = ${devtoolsTargetId})

Error message

Missing target for DevTools page (id = ${devtoolsTargetId})

What it means

Thrown by Browser._getDevToolsTargetPage when waitForTarget returns no CdpTarget matching the requested DevTools target id. This is an internal invariant check: the DevTools target id returned by Target.getDevToolsTarget should appear in the target tree, but no live, matching target was found. It signals that the DevTools target vanished or was never exposed by the target manager within the wait window.

Source

Thrown at packages/puppeteer-core/src/cdp/Browser.ts:479

    return page;
  }

  async _createDevToolsPage(pageTargetId: string): Promise<Page> {
    const openDevToolsResponse = await this.#connection.send(
      'Target.openDevTools',
      {
        targetId: pageTargetId,
      },
    );
    return await this._getDevToolsTargetPage(openDevToolsResponse.targetId);
  }

  async _getDevToolsTargetPage(devtoolsTargetId: string): Promise<Page> {
    const target = (await this.waitForTarget(t => {
      return (t as CdpTarget)._targetId === devtoolsTargetId;
    })) as CdpTarget;
    if (!target) {
      throw new Error(
        `Missing target for DevTools page (id = ${devtoolsTargetId})`,
      );
    }
    const initialized =
      (await target._initializedDeferred.valueOrThrow()) ===
      InitializationStatus.SUCCESS;
    if (!initialized) {
      throw new Error(
        `Failed to create target for DevTools page (id = ${devtoolsTargetId})`,
      );
    }
    const page = await target.page();
    if (!page) {
      throw new Error(
        `Failed to create a DevTools Page for target (id = ${devtoolsTargetId})`,
      );
    }
    return page;

View on GitHub (pinned to d484e21c17)

Solutions

  1. Ensure the targetFilterCallback passed at browser launch returns true for the DevTools target type, or use the default filter.
  2. Retry the call after the browser/target has fully settled, or wait for the page target to be stable before requesting its DevTools target.
  3. Confirm the underlying Chrome build supports Target.getDevToolsTarget (some embedders/headless shells do not).
  4. If reproducing during teardown, guard the caller with a browser/region isAlive check before issuing the request.

Example fix

// before
const page = await browser._getDevToolsTargetPage(devtoolsTargetId);

// after: avoid the helper, or wait for stability first
await pageTarget.initialized();
const page = await browser._getDevToolsTargetPage(devtoolsTargetId);
Defensive patterns

Strategy: try-catch

Validate before calling

// Confirm the page target is alive and initialized before requesting its DevTools target
if (page.isClosed()) {
  throw new Error('page closed; cannot open DevTools target');
}
await page.target().initialized();

Type guard

function hasDevToolsTargetId(resp: unknown): resp is { targetId: string } {
  return typeof resp === 'object' && resp !== null && typeof (resp as any).targetId === 'string';
}

Try / catch

try {
  const devtoolsPage = await browser._getDevToolsTargetPage(devtoolsTargetId);
} catch (e) {
  if (/Missing target for DevTools page/.test((e as Error).message)) {
    // target vanished; re-request the DevTools target id or give up
  } else throw e;
}

Prevention

When it happens

Trigger: Calling page.target().createCDPSession / devtools flows that rely on _getDevToolsTargetPage; explicitly invoking Target.getDevToolsTarget and then waitForTarget with the returned id; DevTools target gets destroyed between the getDevToolsTarget call and the waitForTarget resolution; the target manager's filter rejects the DevTools target (targetFilterCallback), so it is never exposed.

Common situations: Custom targetFilterCallback that filters out non-page targets and also drops the DevTools target; browser closing or target being torn down mid-call; headless shell builds that do not expose a DevTools target; race after a crash or detachment where the id becomes stale.

Related errors

AI-assisted analysis of puppeteer/puppeteer@d484e21c17 (2026-08-12). Data as JSON: /api/errors/da5fa383ca6bf9f3. Report an issue: GitHub.