What causes "Failed to resolve the remote browser endpoint." in apify/crawlee?

Inspect error.cause for the underlying resolution failure.

apify/crawlee · critical · BrowserLaunchError

Failed to resolve the remote browser endpoint.

Error message

Failed to resolve the remote browser endpoint.

What it means

When connecting to a remote browser over CDP/WebSocket, the plugin first asks the connection factory to resolve the endpoint (URL + auth token). This BrowserLaunchError is thrown when that resolution step fails for any reason; the original cause is preserved in `error.cause`. It means the library never even got to the point of opening a WebSocket connection.

Source

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

     * Resolves a remote endpoint via the injected {@apilink RemoteConnection}, stores the session token on
     * the launch context (so the controller can release it on close), and runs the library-specific `connect`.
     * On failure the session is released and the error is wrapped in a {@apilink BrowserLaunchError}.
     *
     * Subclasses implement only the `connect` callback — the resolve / token / release / error-wrap scaffolding
     * lives here so it stays identical across plugins.
     */
    protected async connectToRemoteBrowser(
        launchContext: LaunchContext<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult>,
        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

View on GitHub (pinned to dbe57fb09c)

Solutions

Inspect error.cause for the underlying resolution failure.
Verify credentials/token and that the remote browser service is reachable (network, VPN, firewall).
Check the proxyUrl passed in launch options is valid.
Retry the launch — transient API/network failures often resolve on retry.

Example fix

// before
const pool = new BrowserPool({ browserPlugins: [new MyRemotePlugin()] }); // resolve fails silently at launch
// after
try {
    await pool.newPage();
} catch (err) {
    console.error('resolve failed:', err.cause); // inspect the root cause
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: verify credentials/env are set
if (!process.env.APIFY_TOKEN) throw new Error('missing remote browser token');

Try / catch

try {
    const page = await pool.newPage();
} catch (err) {
    if (err.message.includes('Failed to resolve the remote browser endpoint')) {
        console.error('endpoint resolution failed, cause:', err.cause);
        // retry with backoff or fix credentials/proxy
    } else throw err;
}

Prevention

Validate tokens/env vars before launch
Test network reachability to the remote browser service
Log err.cause for diagnosis; add retries with backoff

When it happens

Trigger: Using BrowserPool with Crawlee's remote-browser connection plugin (e.g. APIFY headless browser connector) where `connection.resolve({ proxyUrl })` throws — invalid or expired browser credentials, unreachable API, bad proxyUrl, or missing environment token.

Common situations: Connecting to Apify's live-view/remote browser; misconfigured APIFY_TOKEN or proxy settings; network/VPN issues preventing the endpoint API from being reached; expired browser session token.

Related errors

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