{"record":{"id":"914ee25e0093cc43","repo":"apify/crawlee","slug":"failed-to-resolve-the-remote-browser-endpoint","errorCode":null,"errorMessage":"Failed to resolve the remote browser endpoint.","messagePattern":"Failed to resolve the remote browser endpoint\\.","errorType":"exception","errorClass":"BrowserLaunchError","httpStatus":null,"severity":"critical","filePath":"packages/browser-pool/src/abstract-classes/browser-plugin.ts","lineNumber":183,"sourceCode":"     * Resolves a remote endpoint via the injected {@apilink RemoteConnection}, stores the session token on\n     * the launch context (so the controller can release it on close), and runs the library-specific `connect`.\n     * On failure the session is released and the error is wrapped in a {@apilink BrowserLaunchError}.\n     *\n     * Subclasses implement only the `connect` callback — the resolve / token / release / error-wrap scaffolding\n     * lives here so it stays identical across plugins.\n     */\n    protected async connectToRemoteBrowser(\n        launchContext: LaunchContext<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult>,\n        connect: (url: string) => Promise<LaunchResult>,\n    ): Promise<LaunchResult> {\n        const connection = this.remoteConnection!;\n\n        let url: string;\n        let token: number;\n        try {\n            ({ url, token } = await connection.resolve({ proxyUrl: launchContext.proxyUrl }));\n        } catch (cause) {\n            throw new BrowserLaunchError('Failed to resolve the remote browser endpoint.', { cause });\n        }\n\n        launchContext.remoteToken = token;\n\n        try {\n            return await connect(url);\n        } catch (cause) {\n            await connection.release(token);\n            throw new BrowserLaunchError(\n                `Failed to connect to remote browser at \"${sanitizeEndpointForLog(url)}\". ` +\n                    'Check that the endpoint is reachable and accepts the configured protocol.',\n                { cause },\n            );\n        }\n    }\n\n    /**\n     * Creates a `LaunchContext` with all the information needed","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/browser-pool/src/abstract-classes/browser-plugin.ts#L165-L201","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst pool = new BrowserPool({ browserPlugins: [new MyRemotePlugin()] }); // resolve fails silently at launch\n// after\ntry {\n    await pool.newPage();\n} catch (err) {\n    console.error('resolve failed:', err.cause); // inspect the root cause\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight: verify credentials/env are set\nif (!process.env.APIFY_TOKEN) throw new Error('missing remote browser token');","typeGuard":null,"tryCatchPattern":"try {\n    const page = await pool.newPage();\n} catch (err) {\n    if (err.message.includes('Failed to resolve the remote browser endpoint')) {\n        console.error('endpoint resolution failed, cause:', err.cause);\n        // retry with backoff or fix credentials/proxy\n    } else throw err;\n}","preventionTips":["Validate tokens/env vars before launch","Test network reachability to the remote browser service","Log err.cause for diagnosis; add retries with backoff"],"tags":["network","remote-browser","launch"],"backgroundTag":"remote-browser-endpoint-resolution-failed","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}