vercel/ai · critical

OpenCode session create failed: ${formatError(created.error)

Error message

OpenCode session create failed: ${formatError(created.error)}

What it means

ensureSession creates an OpenCode session via the legacy session-create API before a turn can run. If that API call returns an error result, the bridge throws with the formatted OpenCode error. This means the OpenCode server refused or failed the session creation request.

Source

Thrown at packages/harness-opencode/src/bridge/index.ts:590

  client: OpenCodeClient;
  start: StartMessage;
  emit: Emit;
}): Promise<string> {
  if (runtime.sessionId) return runtime.sessionId;
  if (start.resumeSessionId) {
    const existing = await legacySessionGet({
      client,
      sessionId: start.resumeSessionId,
    }).catch(() => undefined);
    if (existing && !existing.error) {
      runtime.sessionId = start.resumeSessionId;
      emit({ type: 'bridge-thread', threadId: runtime.sessionId });
      return runtime.sessionId;
    }
  }
  const created = await legacySessionCreate({ client });
  if (created.error) {
    throw new Error(
      `OpenCode session create failed: ${formatError(created.error)}`,
    );
  }
  const id = readSessionId(created.data);
  if (!id) throw new Error('OpenCode session create returned no id.');
  runtime.sessionId = id;
  emit({ type: 'bridge-thread', threadId: id });
  return id;
}

async function runPrompt({
  client,
  sessionId,
  start,
  turn,
  emit,
}: {
  client: OpenCodeClient;

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Read the formatted OpenCode error in the message for the server's own reason and address it.
2. Confirm the OpenCode server is running and reachable at the configured base URL.
3. Check that your OpenCode version matches what the harness bridge expects (update either side if the API changed).
4. Verify server configuration/auth (API keys, provider config) that session creation depends on.

Example fix

// before: server not started
const agent = createOpenCodeHarness();
await agent.run(...); // throws
// after: ensure the server is up first
await spawnOrVerifyOpenCodeServer({ port: 4096 });
const agent = createOpenCodeHarness({ baseURL: 'http://localhost:4096' });
await agent.run(...);

const base = process.env.OPENCODE_BASE_URL ?? 'http://localhost:4096';
await fetch(`${base}/session`, { method: 'GET' }).then(r => { if (!r.ok) throw new Error('OpenCode server not healthy'); });

function isSessionCreateError(e: unknown): e is Error {
  return e instanceof Error && e.message.startsWith('OpenCode session create failed:');
}

try {
  await agent.run(...);
} catch (e) {
  if (isSessionCreateError(e)) {
    console.error('OpenCode create error detail:', e.message.replace('OpenCode session create failed: ', ''));
    // verify server is running / version-compatible, then retry
  } else throw e;
}

When it happens

Trigger: Calling a harness run (which calls sessionId -> ensureSession) when legacySessionCreate returns created.error — typically because the OpenCode server is unreachable, its HTTP API version changed, or the server rejects the create request (bad config, auth, unsupported API).

Common situations: OpenCode server not running or wrong baseURL configured; OpenCode upgraded and the session-create endpoint/response shape changed; missing or invalid API credentials; server-side model/provider configuration invalid.

Related errors

• OpenCode prompt failed: ${formatError(prompted.error)}
• OpenCode compaction failed: ${formatError(compacted.error)}
• OpenCode session create returned no id.
• Failed to fetch the response.
• The response body is empty.

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