{"record":{"id":"c367eb5c64e7ab2c","repo":"vercel/ai","slug":"acp-session-initialization-failed-causemessage","errorCode":null,"errorMessage":"ACP session initialization failed: ${causeMessage}","messagePattern":"ACP session initialization failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/bridge/index.ts","lineNumber":145,"sourceCode":"    const timer = setTimeout(finish, 1000);\n    timer.unref();\n    void hostToolRelay.close().finally(() => {\n      clearTimeout(timer);\n      finish();\n    });\n  },\n});\n\nasync function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {\n  let initialHostToolCatalogRefreshRequired: boolean;\n  try {\n    ({ initialHostToolCatalogRefreshRequired } = await ensureSession({\n      start,\n      turn,\n    }));\n  } catch (error) {\n    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  }","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/bridge/index.ts#L127-L163","documentation":"In the ACP v1 bridge's runTurn, any failure from ensureSession that is not a HarnessBridgeCapabilityUnsupportedError is rethrown as an ACP bridge error with stage 'session initialization' and the original error attached as cause (message: 'ACP session initialization failed: <cause>'). It indicates the underlying agent process/session handshake failed, e.g. spawn, protocol, or agent-side errors.","triggerScenarios":"Starting a turn on an ACP v1 harness when ensureSession fails: agent binary missing or crashing, ACP handshake/initialize failing, session/new rejected, or any non-capability error during session setup.","commonSituations":"Agent CLI not installed or wrong path configured; agent version speaking an incompatible ACP protocol; agent process exiting during startup; permission/auth failures surfaced by the agent during initialization.","solutions":["Inspect error.cause (and the agent's stderr output) to find the underlying failure.","Verify the agent command/binary is installed, on PATH, and supports the ACP v1 protocol version.","Fix agent-side configuration (auth, permissions, working directory) indicated by the cause.","Retry after resolving; if the agent crashed on startup, check its logs for a startup exception."],"exampleFix":"// before\nconst session = await createACPV1({ command: 'my-agent' }); // binary not installed\n// after\n// npm install -g my-agent  (or set command to the installed binary path)\nconst session = await createACPV1({ command: 'my-agent' });","handlingStrategy":"try-catch","validationCode":"// before starting a turn:\nawait (async () => {\n  const which = await checkBinaryOnPath(agentCommand); // e.g. `command -v`\n  if (!which) throw new Error(`ACP agent binary not found: ${agentCommand}`);\n})();","typeGuard":"function isACPBridgeError(e: unknown): e is { name: string; message: string; stage?: string; cause?: unknown } {\n  return typeof e === 'object' && e !== null &&\n    (e as any).name === 'AI_ACPBridgeError' &&\n    typeof (e as any).message === 'string';\n}","tryCatchPattern":"try {\n  await session.prompt(msg);\n} catch (e) {\n  if (isACPBridgeError(e) && String(e.message).startsWith('ACP session initialization failed')) {\n    console.error('cause:', e.cause); // inspect underlying spawn/handshake failure\n    // fix agent binary/protocol/config, then retry\n  } else throw e;\n}","preventionTips":["Verify the agent binary is installed and on PATH before creating the harness","Pin an agent version compatible with ACP v1 and test the initialize handshake in CI","Capture and review agent stderr; most initialization failures are logged there","Read error.cause — the bridge always attaches the original error"],"tags":["acp","session-initialization","bridge","process-startup"],"backgroundTag":"session-initialization-failed","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}