{"record":{"id":"d6aa3700c910c2a2","repo":"vercel/ai","slug":"the-host-tool-mcp-relay-is-unavailable","errorCode":null,"errorMessage":"The host tool MCP relay is unavailable.","messagePattern":"The host tool MCP relay is unavailable\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/bridge/index.ts","lineNumber":162,"sourceCode":"    if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) throw error;\n    throw createACPBridgeError({\n      stage: 'session initialization',\n      cause: error,\n    });\n  }\n  const activeSession = session;\n  if (activeSession == null) {\n    throw new Error('ACP session initialization did not produce a session.');\n  }\n  const activeAgentResponseStreamFailure = agentResponseStreamFailure;\n  if (activeAgentResponseStreamFailure == null) {\n    throw new Error(\n      'ACP session initialization did not start stderr monitoring.',\n    );\n  }\n  const activeHostToolRelay = hostToolRelay;\n  if (activeHostToolRelay == null) {\n    throw new Error('The host tool MCP relay is unavailable.');\n  }\n  if (start.recoveryMode?.type === 'lossy-rerun') {\n    const marker = {\n      type: 'acp-recovery',\n      mode: 'lossy-rerun',\n      reason: start.recoveryMode.reason,\n    } as const;\n    turn.emit({ type: 'raw', rawValue: marker });\n    turn.bridgeLog({\n      level: 'warn',\n      subsystem: 'acp.recovery',\n      message:\n        'The ACP process was replaced; the original prompt is being rerun against the resumed ACP session.',\n      attrs: marker,\n    });\n    turn.emitWarning({\n      message:\n        'ACP process-loss recovery is rerunning the interrupted prompt and may repeat work.',","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/bridge/index.ts#L144-L180","documentation":"runTurn asserts that the local host tool MCP relay server was started during initialization (hostToolRelay non-null) before executing the turn, because agent tool calls that need host-side execution must be able to reach this relay. If the relay was never created or failed to start silently, this Error is thrown and the turn aborts.","triggerScenarios":"The hostToolRelay variable is null at the point in runTurn where the turn starts — the relay HTTP server was never constructed, or its startup failed without surfacing, e.g. the loopback listener on 127.0.0.1 could not be bound.","commonSituations":"System restrictions blocking binding a loopback socket (strict firewalls, containers without networking, restricted sandboxes); resource exhaustion preventing server startup; a bridge bug skipping relay creation; running in an environment where ephemeral port listeners are disallowed.","solutions":["Ensure the environment allows binding an HTTP server on 127.0.0.1 (check firewall/sandbox/container networking rules).","Look for earlier relay startup errors in logs (port allocation or server 'error' events) and fix the underlying cause.","Retry after resolving resource/network issues; if it persists without an environment cause, report as a bridge bug."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"const canBindLoopback = await new Promise<boolean>(resolve => {\n  const s = new Server();\n  s.once('error', () => resolve(false));\n  s.listen(0, '127.0.0.1', () => s.close(() => resolve(true)));\n});\nif (!canBindLoopback) throw new Error('Loopback listener unavailable for host tool relay');","typeGuard":null,"tryCatchPattern":"try {\n  await bridge.runTurn({ prompt });\n} catch (error) {\n  if (error instanceof Error && error.message.includes('host tool MCP relay is unavailable')) {\n    // check environment for socket-binding restrictions, then retry or recreate bridge\n  }\n  throw error;\n}","preventionTips":["Run in environments that allow binding ephemeral loopback ports.","Avoid firewalls/sandboxes that block 127.0.0.1 listeners for the harness process.","Verify relay startup succeeded in logs before running long turns."],"tags":["acp","mcp","relay","network"],"backgroundTag":"relay-server-unavailable","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}