apify/crawlee · critical · BrowserLaunchError

Failed to connect to remote browser at "${sanitizeEndpointFo

Error message

Failed to connect to remote browser at "${sanitizeEndpointForLog(url)}". Check that the endpoint is reachable and accepts the configured protocol.

What it means

After successfully resolving the remote endpoint, the plugin attempts to open a WebSocket/CDP connection with `connect(url)`. This BrowserLaunchError wraps any failure of that connect step, and releases the reserved connection token before rethrowing. The sanitized URL (secrets stripped) is included in the message, with the raw failure in `error.cause`.

Source

Thrown at packages/browser-pool/src/abstract-classes/browser-plugin.ts:192

        connect: (url: string) => Promise<LaunchResult>,
    ): Promise<LaunchResult> {
        const connection = this.remoteConnection!;

        let url: string;
        let token: number;
        try {
            ({ url, token } = await connection.resolve({ proxyUrl: launchContext.proxyUrl }));
        } catch (cause) {
            throw new BrowserLaunchError('Failed to resolve the remote browser endpoint.', { cause });
        }

        launchContext.remoteToken = token;

        try {
            return await connect(url);
        } catch (cause) {
            await connection.release(token);
            throw new BrowserLaunchError(
                `Failed to connect to remote browser at "${sanitizeEndpointForLog(url)}". ` +
                    'Check that the endpoint is reachable and accepts the configured protocol.',
                { cause },
            );
        }
    }

    /**
     * Creates a `LaunchContext` with all the information needed
     * to launch a browser. Aside from library specific launch options,
     * it also includes internal properties used by `BrowserPool` for
     * management of the pool and extra features.
     */
    createLaunchContext(
        options: CreateLaunchContextOptions<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult> = {},
    ): LaunchContext<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult> {
        const {
            id,

View on GitHub (pinned to dbe57fb09c)

Solutions

1. Read error.cause to see the underlying connect failure (ECONNREFUSED, TLS, auth).
2. Verify the endpoint URL is reachable from your environment (curl / websocket client test).
3. Confirm protocol compatibility between client library and remote browser service.
4. Retain the released token/connection semantics — retry the whole launch so a fresh token is resolved.

Example fix

// before
await pool.newPage(); // throws BrowserLaunchError
// after
try {
    await pool.newPage();
} catch (err) {
    console.error('connect failed at endpoint:', err.message, '\ncause:', err.cause);
    // then retry launch with backoff or fix network/TLS config
}

// pre-flight reachability check
const ok = await fetch(url.replace('ws', 'http'), { method: 'HEAD' }).then(r => r.ok).catch(() => false);
if (!ok) throw new Error('remote browser endpoint unreachable');

try {
    const page = await pool.newPage();
} catch (err) {
    if (err.message.startsWith('Failed to connect to remote browser at')) {
        console.error('connect failed, cause:', err.cause);
        await sleep(backoff); return pool.newPage(); // retry launch (fresh token)
    } throw err;
}

When it happens

Trigger: connect(url) throwing during _launch of a remote-browser plugin: the endpoint URL resolved but the browser service rejects the protocol, the browser process is down, TLS/auth handshake fails, or the WebSocket is refused.

Common situations: Remote browser host unreachable from the execution environment (container networking, firewall); wrong websocket protocol or version mismatch; endpoint requires TLS the client doesn't trust; token valid at resolve time but connection refused afterwards.

Related errors

• Failed to resolve the remote browser endpoint.
• Request blocked - received ${statusCode} status code.
• ${this.getMessageFromError(error)}
• ${errorMessage.join(' ')}​
• Remote browser endpoint resolved to an empty string.

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