apify/crawlee · error · Error

browserController.newPage() failed: ${browserController.id}

Error message

browserController.newPage() failed: ${browserController.id}
Cause:${(err as Error).message}.

What it means

createPageForBrowser wraps browserController.newPage(); if the underlying controller fails to open a page (browser crashed, context closed, CDP error, navigation/timeout in controller internals), the pool retires the browser controller and rethrows a plain Error that embeds the controller id and the original message. The original error becomes part of the message text (after 'Cause:'), not error.cause.

Source

Thrown at packages/browser-pool/src/browser-pool.ts:643

                async () => browserController.newPage(finalPageOptions),
                this.operationTimeoutMillis,
                'browserController.newPage() timed out.',
            )) as PageReturn;
            tryCancel();

            this.pages.set(pageId, page);
            this.pageIds.set(page, pageId);
            this.pageToBrowserController.set(page, browserController);

            // if you synchronously trigger a lot of page launches, browser will not get retired soon enough. Not sure if it's a problem, let's monitor it.
            if (browserController.totalPages >= this.retireBrowserAfterPageCount) {
                this.retireBrowserController(browserController);
            }

            this.overridePageClose(page);
        } catch (err) {
            this.retireBrowserController(browserController);
            throw new Error(
                `browserController.newPage() failed: ${browserController.id}\nCause:${(err as Error).message}.`,
            );
        }

        await this.executeHooks(this.postPageCreateHooks, page, browserController);
        tryCancel();

        this.emit(BROWSER_POOL_EVENTS.PAGE_CREATED, page);

        return page;
    }

    /**
     * Removes a browser controller from the pool. The underlying
     * browser will be closed after all its pages are closed.
     *
     */
    retireBrowserController(browserController: BrowserControllerReturn): void {

View on GitHub (pinned to dbe57fb09c)

Solutions

Parse the message after 'Cause:' (or catch and read err.message) to find the root failure.
Retry the page creation — the failed controller was already retired so the pool will launch a fresh browser.
Reduce concurrent page count / increase container memory if the cause is OOM or resource exhaustion.
For remote browsers, verify connectivity and consider connection retry/backoff before launching.

Example fix

// before
await pool.newPage(); // may throw 'browserController.newPage() failed: ...
Cause:Target closed'
// after
let page;
try {
    page = await pool.newPage();
} catch (err) {
    console.warn('page creation failed, retrying with fresh browser:', err.message);
    page = await pool.newPage(); // retired controller ensures a new browser is launched
}

Defensive patterns

Strategy: retry

Try / catch

try {
    page = await pool.newPage();
} catch (err) {
    if (err.message.startsWith('browserController.newPage() failed')) {
        const cause = err.message.split('Cause:')[1];
        console.warn('newPage failed:', cause, '— retrying (controller retired)');
        page = await pool.newPage();
    } else throw err;
}

Prevention

Retry once — the pool already retired the bad controller and will launch a fresh browser
Monitor memory/OOM in containers; cap concurrency to avoid browser crashes
Keep remote connections stable; add network retry/backoff for remote browsers

When it happens

Trigger: browserController.newPage() throwing inside createPageForBrowser — reached via pool.newPage() or pool.newPageInNewBrowser() — e.g. browser process crashed or disconnected, context/page target closed, or plugin-specific newPage failure.

Common situations: Browser killed by OOM in constrained containers; remote browser connection dropped mid-session; too many concurrent pages exhausting the browser; puppeteer/playwright TargetClosedError after crash.

Related errors

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/f8cab8f1f1962b53. Report an issue: GitHub.