Yeachan-Heo/oh-my-codex · error · Error

tmux_instance_mismatch

tmux_instance_mismatch

Error message

tmux_instance_mismatch:${tmuxSessionName}:${instanceId || "missing"}

What it means

Before sending a prompt to a bound tmux session, the bridge verifies the tmux session's OMX instance option matches the recorded session_id, ensuring prompts go to the right agent instance. A mismatch (or missing option) throws with the session name and detected instance id.

Source

Thrown at src/mcp/hermes-bridge.ts:215

  sessionId: string,
  prompt: string,
  deps: HermesBridgeDeps,
): Promise<HermesTmuxPromptResult | null> {
  const rawSession = await readSessionState(cwd);
  if (!rawSession || !sessionMatchesRequested(rawSession, sessionId)) return null;
  const tmuxSessionName = optionalString(rawSession.tmux_session_name);
  const tmuxPaneId = optionalString(rawSession.tmux_pane_id);
  if (!tmuxSessionName || !tmuxPaneId) return null;
  if (!isTmuxPaneId(tmuxPaneId)) {
    throw new Error(`unsupported_session_kind:invalid_tmux_pane_binding:${tmuxSessionName}`);
  }

  const execTmux = deps.execTmuxFileSync ?? defaultExecTmuxFileSync;
  try {
    execTmux(["has-session", "-t", tmuxSessionName]);
    const instanceId = String(execTmux(["show-options", "-qv", "-t", tmuxSessionName, OMX_INSTANCE_OPTION]) ?? "").trim();
    if (instanceId !== rawSession.session_id) {
      throw new Error(`tmux_instance_mismatch:${tmuxSessionName}:${instanceId || "missing"}`);
    }
    const paneSession = String(execTmux(["display-message", "-p", "-t", tmuxPaneId, "#{session_name}"]) ?? "").trim();
    if (paneSession !== tmuxSessionName) {
      throw new Error(`pane_session_mismatch:${tmuxPaneId}:${paneSession || "missing"}`);
    }
    for (const argv of buildSendPaneArgvs(tmuxPaneId, prompt, true)) {
      execTmux(argv);
    }
  } catch (error) {
    const message = errorMessage(error);
    const reason = message.startsWith("tmux_instance_mismatch") || message.startsWith("pane_session_mismatch")
      ? message
      : "tmux_send_failed";
    throw new Error(`unsupported_session_kind:tmux_prompt_delivery_failed:${tmuxSessionName}:${tmuxPaneId}:${reason}`);
  }
  return {
    session_id: rawSession.session_id,
    tmux_session_name: tmuxSessionName,

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Restart the target session so the tmux option is set correctly
2. Kill the stale tmux session if it belongs to a dead instance
3. Avoid reusing tmux session names across instances

const inst = execSync(`tmux show-options -qv -t ${sessionName} ${OMX_INSTANCE_OPTION}`).toString().trim();
if (inst !== state.session_id) { /* rebind or restart before calling */ }

catch (e) { if ((e as Error).message.startsWith('tmux_instance_mismatch')) { /* restart target session, then retry send */ } }

When it happens

Trigger: execTmux show-options -qv on the bound tmux session returns an instance id different from rawSession.session_id, or returns nothing ('missing') because the option was never set.

Common situations: The tmux session was reused/recreated by a newer instance, the option was cleared, or two agent instances share a tmux session name.

Related errors

• unsupported_session_kind
• pane_session_mismatch
• ${name} is required
• ${name} must be a string
• ${name} must be non-empty

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/b04063f591787603. Report an issue: GitHub.