vercel/ai · error · Error

ACP session initialization failed: ${causeMessage}

Error message

ACP session initialization failed: ${causeMessage}

What it means

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.

Source

Thrown at packages/harness-acp/src/v1/bridge/index.ts:145

    const timer = setTimeout(finish, 1000);
    timer.unref();
    void hostToolRelay.close().finally(() => {
      clearTimeout(timer);
      finish();
    });
  },
});

async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
  let initialHostToolCatalogRefreshRequired: boolean;
  try {
    ({ initialHostToolCatalogRefreshRequired } = await ensureSession({
      start,
      turn,
    }));
  } catch (error) {
    if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) throw error;
    throw createACPBridgeError({
      stage: 'session initialization',
      cause: error,
    });
  }
  const activeSession = session;
  if (activeSession == null) {
    throw new Error('ACP session initialization did not produce a session.');
  }
  const activeAgentResponseStreamFailure = agentResponseStreamFailure;
  if (activeAgentResponseStreamFailure == null) {
    throw new Error(
      'ACP session initialization did not start stderr monitoring.',
    );
  }
  const activeHostToolRelay = hostToolRelay;
  if (activeHostToolRelay == null) {
    throw new Error('The host tool MCP relay is unavailable.');
  }

View on GitHub (pinned to 69428b1f8b)

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.

Example fix

// before
const session = await createACPV1({ command: 'my-agent' }); // binary not installed
// after
// npm install -g my-agent  (or set command to the installed binary path)
const session = await createACPV1({ command: 'my-agent' });

Defensive patterns

Strategy: try-catch

Validate before calling

// before starting a turn:
await (async () => {
  const which = await checkBinaryOnPath(agentCommand); // e.g. `command -v`
  if (!which) throw new Error(`ACP agent binary not found: ${agentCommand}`);
})();

Type guard

function isACPBridgeError(e: unknown): e is { name: string; message: string; stage?: string; cause?: unknown } {
  return typeof e === 'object' && e !== null &&
    (e as any).name === 'AI_ACPBridgeError' &&
    typeof (e as any).message === 'string';
}

Try / catch

try {
  await session.prompt(msg);
} catch (e) {
  if (isACPBridgeError(e) && String(e.message).startsWith('ACP session initialization failed')) {
    console.error('cause:', e.cause); // inspect underlying spawn/handshake failure
    // fix agent binary/protocol/config, then retry
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/c367eb5c64e7ab2c. Report an issue: GitHub.