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

preLaunch setup finalization failed

Error message

preLaunch setup finalization failed

What it means

During pre-launch setup finalization, one or more cleanup/close steps failed; the individual errors are collected and rethrown as an AggregateError with the message 'preLaunch setup finalization failed'. It signals that teardown of launch artifacts (e.g. bound session close) partially failed, not that the original launch setup itself failed.

Source

Thrown at src/cli/index.ts:6183

  Object.assign(error, { establishmentCleanup: established.cleanup });
  throw error;
}

async function failPreLaunchSetup(binding: LaunchSessionBinding): Promise<void> {
  const failures: unknown[] = [];
  try {
    await finalizeBoundOnce(binding, "setup-failure");
  } catch (error) {
    failures.push(error);
  } finally {
    try {
      const close = await closeLaunchSessionBindingOnce(binding);
      if (close.status === "failed") failures.push(close.error ?? new Error("bound session close failed"));
    } catch (error) {
      failures.push(error);
    }
  }
  if (failures.length > 0) throw new AggregateError(failures, "preLaunch setup finalization failed");
}

async function completePreLaunchSetup(
  cwd: string,
  sessionId: string,
  notifyTempContract: NotifyTempContract | undefined,
  codexHomeOverride: string | undefined,
  enableNotifyFallbackAuthority: boolean,
  worktreeDirty: boolean,
): Promise<CompletionResult> {
  const degraded: DegradedSetupOperation[] = [];
  try {
    const cleanup = await cleanupLaunchOrphanedMcpProcesses();
    if (cleanup.terminatedCount > 0) console.log(`[omx] Reaped ${cleanup.terminatedCount} orphaned OMX MCP process(es) before launch.`);
    if (cleanup.failedPids.length > 0) console.warn(`[omx] Failed to reap ${cleanup.failedPids.length} orphaned OMX MCP process(es); continuing launch.`);
  } catch (error) {
    degraded.push("orphan-reaping");
    logCliOperationFailure(error);

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Inspect the AggregateError's errors array — each entry names the actual failing finalization step and root cause
2. Verify the tmux session and state files still exist at teardown time; stale references are the usual culprit
3. Retry the launch once transient races clear; then clean state (remove stale session binding files) if it persists
4. Check permissions and disk space in the OMX state directory

Example fix

try {
  await finalizePreLaunch(binding);
} catch (e) {
  if (e instanceof AggregateError) console.error(e.errors); // inspect each underlying failure
  throw e;
}

function isAggregateFinalizationError(e: unknown): e is AggregateError {
  return e instanceof AggregateError && e.message === "preLaunch setup finalization failed";
}

try { await finalize(); } catch (e) { if (isAggregateFinalizationError(e)) { for (const inner of e.errors) log(inner); /* state is partially cleaned; safe to relaunch */ } }

When it happens

Trigger: The finalization loop runs closeLaunchSessionBindingOnce over bound sessions and collects failures; any throw (IPC close error, missing state file during teardown, tmux command failure while closing) lands in the failures array and triggers the aggregate throw.

Common situations: The tmux session died mid-setup so close commands target a dead session; filesystem permission problems removing state files; races where another OMX process already cleaned the binding; disk-full conditions during teardown writes.

Related errors

• detached post-launch lifecycle cleanup failed
• failed to kill tmux pane ${finalProof.paneId}: ${result.stde
• failed to kill tmux pane ${killTarget}: ${killed.stderr}
• invalid auth slot path
• auth directory must not be a symlink: ${dir}

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