{"record":{"id":"60ffbc6fa76bd2f2","repo":"microsoft/playwright","slug":"syncserver-failed-to-bind-http-server","errorCode":null,"errorMessage":"SyncServer: failed to bind HTTP server","messagePattern":"SyncServer: failed to bind HTTP server","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/playwright-core/src/server/webkit/webview/syncServer.ts","lineNumber":52,"sourceCode":"// the endpoint cannot be discovered by a script running in the page just by\n// knowing the (randomly bound) port.\nexport class SyncServer {\n  private readonly _server: Server;\n  private readonly _baseUrl: string;\n  private readonly _handlers = new Map<string, SyncHandler>();\n\n  static async start(): Promise<SyncServer> {\n    const server = createHttpServer();\n    await new Promise<void>((resolve, reject) => {\n      server.once('error', reject);\n      server.listen(0, '127.0.0.1', () => {\n        server.removeListener('error', reject);\n        resolve();\n      });\n    });\n    const address = server.address();\n    if (!address || typeof address === 'string')\n      throw new Error('SyncServer: failed to bind HTTP server');\n    return new SyncServer(server, `http://127.0.0.1:${address.port}`);\n  }\n\n  private constructor(server: Server, baseUrl: string) {\n    this._server = server;\n    this._baseUrl = baseUrl;\n    this._server.on('request', (req, res) => this._handleRequest(req, res));\n  }\n\n  addHandler(handler: SyncHandler): SyncHandlerRegistration {\n    const guid = createGuid();\n    this._handlers.set(guid, handler);\n    return {\n      endpoint: `${this._baseUrl}/${guid}`,\n      dispose: () => this._handlers.delete(guid),\n    };\n  }\n","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/microsoft/playwright/blob/c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6/packages/playwright-core/src/server/webkit/webview/syncServer.ts#L34-L70","documentation":"SyncServer.start() binds a tiny loopback HTTP server (listen 0 on 127.0.0.1) for page-side synchronous XHR callbacks during webview automation. After listen resolves, it reads server.address(); if the address is missing or a string (pipe name) instead of an {port} object, the bind is considered failed and the server cannot be used. This is an internal startup failure for the iOS/Safari webview path.","triggerScenarios":"Constructing a WVBrowser/SyncServer when the OS refuses to assign a loopback TCP port, or when the server somehow ends up bound to a pipe/unix socket yielding a string address. Essentially an environment where binding a random loopback port is impossible.","commonSituations":"Heavy process exhaustion (no ephemeral ports available); a sandbox/container that blocks loopback TCP listen; a corrupted Node http server state. Not user-facing in normal Playwright flows.","solutions":["Free up ephemeral ports / reduce parallel browser count on the host.","Ensure the environment allows binding 127.0.0.1:0 (check sandbox/firewall rules).","Retry the connectOverCDP/webview connection; if it persists, report a Playwright bug with the host networking details."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// No deterministic caller guard; ensure loopback TCP is bindable.\n// Check ephemeral port availability on the host before launching webview automation.","typeGuard":null,"tryCatchPattern":"for (let attempt = 0; attempt < 3; attempt++) {\n  try { return await startWebviewSession(); }\n  catch (e) {\n    if (!/SyncServer: failed to bind/i.test(String(e.message)) || attempt === 2) throw e;\n    await new Promise(r => setTimeout(r, 500));\n  }\n}","preventionTips":["Reduce parallel browser/webview count to keep ephemeral ports available.","Confirm the host/container allows binding 127.0.0.1:0.","Report persistent failures as a Playwright environment issue."],"tags":["webview","ios","network","loopback","internal"],"backgroundTag":null,"analyzedSha":"c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6","analyzedAt":"2026-08-12T07:26:36.950Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}