{"record":{"id":"57043fea50f000c0","repo":"apify/crawlee","slug":"failed-to-connect-to-remote-browser-at-sanitize","errorCode":null,"errorMessage":"Failed to connect to remote browser at \"${sanitizeEndpointForLog(url)}\". Check that the endpoint is reachable and accepts the configured protocol.","messagePattern":"Failed to connect to remote browser at \"(.+?)\"\\. Check that the endpoint is reachable and accepts the configured protocol\\.","errorType":"exception","errorClass":"BrowserLaunchError","httpStatus":null,"severity":"critical","filePath":"packages/browser-pool/src/abstract-classes/browser-plugin.ts","lineNumber":192,"sourceCode":"        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\n     * to launch a browser. Aside from library specific launch options,\n     * it also includes internal properties used by `BrowserPool` for\n     * management of the pool and extra features.\n     */\n    createLaunchContext(\n        options: CreateLaunchContextOptions<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult> = {},\n    ): LaunchContext<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult> {\n        const {\n            id,","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/browser-pool/src/abstract-classes/browser-plugin.ts#L174-L210","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read error.cause to see the underlying connect failure (ECONNREFUSED, TLS, auth).","Verify the endpoint URL is reachable from your environment (curl / websocket client test).","Confirm protocol compatibility between client library and remote browser service.","Retain the released token/connection semantics — retry the whole launch so a fresh token is resolved."],"exampleFix":"// before\nawait pool.newPage(); // throws BrowserLaunchError\n// after\ntry {\n    await pool.newPage();\n} catch (err) {\n    console.error('connect failed at endpoint:', err.message, '\\ncause:', err.cause);\n    // then retry launch with backoff or fix network/TLS config\n}","handlingStrategy":"retry","validationCode":"// pre-flight reachability check\nconst ok = await fetch(url.replace('ws', 'http'), { method: 'HEAD' }).then(r => r.ok).catch(() => false);\nif (!ok) throw new Error('remote browser endpoint unreachable');","typeGuard":null,"tryCatchPattern":"try {\n    const page = await pool.newPage();\n} catch (err) {\n    if (err.message.startsWith('Failed to connect to remote browser at')) {\n        console.error('connect failed, cause:', err.cause);\n        await sleep(backoff); return pool.newPage(); // retry launch (fresh token)\n    } throw err;\n}","preventionTips":["Verify endpoint reachability from your runtime (container networking, firewall)","Confirm client/server websocket protocol compatibility","Retry the full launch so a fresh token is resolved"],"tags":["network","websocket","remote-browser","launch"],"backgroundTag":"remote-browser-connect-failed","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}