OpenCode MissingSessionID: what the x-opencode-session error means and how to fix it

If you use OpenCode Go through any kind of proxy, gateway, or router, you may have woken up to every single request failing with the same wall of red:

HTTP 400: {
  "type": "error",
  "error": {
    "type": "MissingSessionID",
    "message": "Error from provider (Console Go): Request is missing x-opencode-session and cannot be routed efficiently."
  }
}

Nothing about your setup changed. Your API key is fine. Your subscription is active. Every model under ocg/ — glm-5.2, kimi-k3, minimax-m3, big-pickle, all of them — fails identically.

This is a provider-side change, and it is worth understanding properly, because the same class of change will happen again with a different provider.

What actually changed

OpenCode began requiring an x-opencode-session header on every request to the Go endpoint. Requests without it are rejected before they reach a model.

The header was not new. It has been part of the OpenCode client's behaviour for a while — the official client sends one, so the official client never noticed. What changed is that the header went from optional to mandatory. The moment enforcement switched on, every integration that had not been sending it broke at once.

That is the important detail for anyone debugging this: there is no gradual failure signal. It is not a rate limit that ramps, or a model that degrades. It is a hard 400 on the first request after enforcement began, and on every request after that.

Why the error message is a little misleading

The message says the request "cannot be routed efficiently", which reads like a performance warning rather than a hard requirement. It is not a warning. The request is refused.

The word "efficiently" is a clue to the purpose of the header, though, and it is worth knowing because it tells you what a correct value looks like.

What the header is actually for

x-opencode-session identifies a conversation. It is not authentication — your API key already does that. It is a routing and caching hint.

When a provider knows that twenty requests belong to one ongoing conversation, it can:

• route them to the same backend node, so the KV cache for that conversation stays warm
• avoid re-processing a long prompt prefix it has already seen
• attribute usage coherently across a multi-turn session

That is why the value has to be stable across the turns of one conversation and different between separate conversations. A random value per request satisfies the presence check and defeats the entire purpose — you get the header accepted and the cache benefit thrown away.

The value itself is opaque. OpenCode does not parse meaning out of it. The shape the official tooling uses is ses_ followed by 32 lowercase hex characters.

Fixing it in kRouter

If you are on kRouter, upgrade:

npm i -g @sifxprime/krouter@latest

Anything from v0.5.151 onward sends the header. Nothing else to configure, no new setting, no key to paste.

A few details of how it behaves, because they matter if you are debugging:

• The value is stable for the life of a conversation, so OpenCode's routing and prompt caching actually work rather than merely being satisfied.
• If your client already speaks OpenCode's protocol and sends its own x-opencode-session, kRouter passes yours through untouched. Overwriting it would split one conversation into two upstream sessions and lose exactly the cache locality the header exists to provide.
• The value is namespaced per client tool, so two different tools that both call their thread "1" do not collide into a single upstream session.
• It is applied to both OpenCode Go transports — the OpenAI-style /chat/completions endpoint and the Anthropic-style /messages endpoint that the MiniMax models use.

Fixing it in your own client

If you are talking to OpenCode Go directly rather than through a router, add the header yourself.

const SESSION_PREFIX = "ses_";
 
// Derive a stable id from something that identifies the conversation — a thread id,
// a chat id, whatever your app already has. Hashing keeps it opaque and fixed-width.
function sessionIdFor(conversationId) {
  const digest = crypto
    .createHash("sha256")
    .update(String(conversationId))
    .digest("hex")
    .slice(0, 32);
  return SESSION_PREFIX + digest;
}
 
await fetch("https://opencode.ai/zen/go/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
    "x-opencode-session": sessionIdFor(thread.id),
  },
  body: JSON.stringify({ model: "glm-5.2", messages, stream: true }),
});

Three things to get right:

1. Same conversation, same value. Derive it from a conversation identifier, not from Date.now() or a fresh UUID per call.
2. Different conversations, different values. If every user shares one hardcoded string, you have handed the provider a single enormous session and the cache behaviour will be worse than sending nothing coherent at all.
3. Do not put anything sensitive in it. It is a header sent on every request. Hash whatever you derive it from rather than passing a raw email, user id, or path.

What to check if it still fails after the fix

If you are on a current version and still seeing MissingSessionID, work through these in order:

• Confirm the version actually running. krouter --version should report 0.5.151 or newer. A globally installed CLI and a locally installed one can disagree; npm i @sifxprime/krouter without -g installs into the current folder and does not update the krouter on your PATH.
• Check which endpoint is failing. If only one model fails and the rest work, the problem is more likely to be that model's transport than the header.
• Look at the actual outgoing request, not the config. A proxy in front of your router can strip unknown headers; that is uncommon but it does happen with corporate egress proxies.

The broader lesson

This is the second time in recent memory a provider has turned an optional header into a required one with no deprecation window. It will not be the last.

If you maintain an integration against a provider API, the defensive posture is:

• Send what the official client sends, even when the API does not currently require it. The official client is the de facto specification, and anything it sends is a candidate for becoming mandatory.
• Treat a 400 with an unfamiliar error type as a contract change, not as a bug in your request construction. MissingSessionID is not a validation error about your payload; it is the provider telling you the contract moved.
• Do not assume silence means stability. A header that has been optional for a year can become required on a Tuesday.

Related reading

• Anthropic rate limits, in depth — how the other major provider signals limits, and what its error shapes actually mean
• The cheapest LLMs for coding in 2026 — where OpenCode Go's bundled models sit against everything else on price

Common questions

Is MissingSessionID a problem with my API key?

No. Authentication is handled by your Authorization header, and an auth failure returns 401 or 403, not 400. MissingSessionID means the request authenticated correctly and was then rejected for a missing routing header.

Can I just send a random value for x-opencode-session?

It will pass the presence check, but you should not. The header exists so the provider can route a conversation's turns to the same warm cache. A fresh value per request makes every turn look like a brand-new conversation, so you lose prompt-cache reuse and pay full price for the prefix each time.

Does this affect every OpenCode Go model?

Yes. The check happens before model routing, so glm-5.2, kimi-k3, kimi-k2.7-code, minimax-m3, big-pickle and the rest all return the same 400.

Which kRouter version fixes it?

v0.5.151 and newer. Upgrade with npm i -g @sifxprime/krouter@latest.

Does kRouter overwrite a session header I send myself?

No. If your client sends a valid x-opencode-session, kRouter forwards it unchanged and does not substitute its own.