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

mailbox_notify_failed:${firstFailure?.reason ?? 'unknown'}

Error message

mailbox_notify_failed:${firstFailure?.reason ?? 'unknown'}

What it means

Thrown after a broadcast when at least one worker's mailbox notify failed; the message contains the first failing outcome's reason (or 'unknown').

Source

Thrown at src/team/runtime.ts:7125

    fallbackAllowed: transportPreference === 'hook_preferred_with_fallback',
    notify: async (target, message) =>
      transportPreference === 'hook_preferred_with_fallback'
        ? { ok: true, transport: 'hook', reason: 'queued_for_hook_dispatch' }
        : (typeof target.workerIndex === 'number'
        ? await notifyWorkerOutcome(config, target.workerIndex, message, target.paneId)
        : { ok: false, transport: 'none', reason: 'missing_worker_index' }),
  });
  const results = await finalizeBroadcastMailboxOutcomes({
    teamName: sanitized,
    outcomes,
    transportPreference,
    config,
    dispatchPolicy,
    cwd,
  });
  if (results.some((result) => !result.ok)) {
    const firstFailure = results.find((result) => !result.ok);
    throw new Error(`mailbox_notify_failed:${firstFailure?.reason ?? 'unknown'}`);
  }
}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Inspect the reason suffix to identify which failure mode hit
2. Verify all workers' panes/processes are alive before broadcasting
3. Treat broadcast as best-effort: catch and retry only to failed workers

Example fix

// before
await broadcastWorkerMessage(teamName, fromWorker, body, cwd);
// after
try { await broadcastWorkerMessage(teamName, fromWorker, body, cwd); }
catch (e) { /* inspect reason, retry to dead workers after restart */ }

const dead = cfg.workers.filter(w => !isWorkerAlive(w)); if (dead.length) await restartWorkers(dead);

try { await broadcastWorkerMessage(...) } catch (e) { if (e.message.startsWith('mailbox_notify_failed:')) { /* partial failure: log and retry targeted workers */ } }

When it happens

Trigger: queueBroadcastMailboxMessage returns per-worker results and any result has ok=false — e.g. one worker's pane is dead while others succeeded.

Common situations: Partially degraded teams: one worker crashed or was scaled down, tmux issues affecting a single pane.

Related errors

• mailbox_notify_failed:${finalOutcome.reason}
• 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
• Usage: omx team [N:agent-type] "<task description>"

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