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

tmux_session_query_unavailable

Error message

tmux_session_query_unavailable

What it means

Thrown by findActiveTeams when the tmux session listing API returns null, meaning tmux is not installed, not running, or its server cannot be queried.

Source

Thrown at src/team/runtime.ts:5689

    const baseSession = config.tmux_session.split(':')[0];
    const teamSessions = getTeamTmuxSessions(sanitized);
    if (!teamSessions.includes(baseSession)) return null;
  }

  return {
    teamName: sanitized,
    sanitizedName: sanitized,
    sessionName: config.tmux_session,
    config,
    cwd,
  };
}

async function findActiveTeams(cwd: string, leaderSessionId: string): Promise<string[]> {
  const root = teamRuntimeTeamsRoot(cwd);
  if (!existsSync(root)) return [];
  const listedSessions = listTeamSessions();
  if (listedSessions === null) throw new Error('tmux_session_query_unavailable');
  const sessions = new Set(listedSessions);

  const entries = await readdir(root, { withFileTypes: true });
  const active: string[] = [];
  for (const e of entries) {
    if (!e.isDirectory()) continue;
    const teamName = e.name;
    const cfg = await readTeamConfig(teamName, cwd);
    const manifest = await readTeamManifestV2(teamName, cwd);
    const governance = resolveGovernancePolicy(manifest?.governance);
    if (governance.one_team_per_leader_session === false) continue;
    const workerLaunchMode = cfg?.worker_launch_mode
      ?? manifest?.policy?.worker_launch_mode
      ?? 'interactive';
    const tmuxSession = (manifest?.tmux_session || cfg?.tmux_session || `omx-team-${teamName}`).split(':')[0];
    if (leaderSessionId) {
      const ownerSessionId = manifest?.leader?.session_id?.trim() ?? '';
      if (ownerSessionId && ownerSessionId !== leaderSessionId) continue;

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Install tmux and ensure it is on PATH
2. Start or verify the tmux server (tmux ls) in the target environment
3. Fix TMUX env vars/socket permissions if using a custom socket

if (listTeamSessions() === null) throw new Error('tmux unavailable — install/start tmux first');

(s: string[] | null): s is string[] => s !== null

When it happens

Trigger: Calling an API that enumerates active teams (e.g. shutdown/cleanup discovery) when listTeamSessions() fails — tmux binary missing, TMUX socket unreachable, or tmux server not started.

Common situations: Running inside a container/CI without tmux, tmux socket permissions issues, or tmux not on PATH.

Related errors

• [sparkshell] raw fallback failed: executable not found (${in
• tmux is unavailable; omx question requires tmux for OMX-owne
• omx question cannot open a visible renderer because this pro
• Team mode requires running inside tmux current leader pane
• invalid auth slot path

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