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

mailbox_notify_failed:${finalOutcome.reason}

Error message

mailbox_notify_failed:${finalOutcome.reason}

What it means

Thrown when sending a mailbox message to the 'leader-fixed' recipient fails; finalOutcome.ok is false and the reason is embedded in the message.

Source

Thrown at src/team/runtime.ts:7063

  body: string,
  cwd: string,
): Promise<DispatchOutcome> {
  const sanitized = sanitizeTeamName(teamName);
  const config = await readTeamConfig(sanitized, cwd);
  if (!config) throw new Error(`Team ${sanitized} not found`);
  const manifest = await readTeamManifestV2(sanitized, cwd);
  const dispatchPolicy = resolveDispatchPolicy(manifest?.policy, config.worker_launch_mode);

  if (toWorker === 'leader-fixed') {
    const finalOutcome = await sendLeaderMailboxMessage({
      teamName: sanitized,
      fromWorker,
      body,
      config,
      dispatchPolicy,
      cwd,
    });
    if (!finalOutcome.ok) throw new Error(`mailbox_notify_failed:${finalOutcome.reason}`);
    return finalOutcome;
  }

  const finalOutcome = await sendRecipientMailboxMessage({
    teamName: sanitized,
    fromWorker,
    toWorker,
    body,
    config,
    dispatchPolicy,
    cwd,
  });
  if (!finalOutcome.ok) throw new Error(`mailbox_notify_failed:${finalOutcome.reason}`);
  return finalOutcome;
}

export async function broadcastWorkerMessage(
  teamName: string,

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Check the embedded reason (e.g. pane_not_found, write_failed)
2. Verify the leader worker/session is alive before dispatching
3. Restart the team or leader worker if its pane is gone

try { await dispatch(...) } catch (e) { if (e.message.startsWith('mailbox_notify_failed:')) { const reason = e.message.split(':')[1]; /* restart leader and retry */ } }

When it happens

Trigger: Dispatching to toWorker='leader-fixed' and the underlying leader mailbox notify (tmux trigger, file queue write, etc.) reports failure.

Common situations: Leader pane/session gone (crashed leader), tmux issues, or mailbox state file write failures.

Related errors

• Worker ${toWorker} not found in team
• mailbox_notify_failed:${firstFailure?.reason ?? 'unknown'}
• Conflicting setup Team mode flags: ${source} selects ${next}
• Invalid setup Team mode: ${next}. Expected one of: enabled,
• Missing setup Team mode value after --team-mode. Expected on

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