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

Missing --handoff-json.

Error message

Missing --handoff-json.

What it means

The `autopilot advance` command requires a handoff payload in addition to --to. This error fires when --handoff-json is absent from the arguments.

Source

Thrown at src/cli/autopilot.ts:147

  }

  const state = await readAutopilot(cwd, sessionId);
  if (!state) throw new Error('No Autopilot state found. Run `omx autopilot start --task <text>` first.');

  if (command === 'status' || command === 'next') {
    const nextInstruction = instruction(state);
    const skippedGates = skippedGateReport(state as unknown as Record<string, unknown>);
    if (json) stdout(JSON.stringify({ state, instruction: nextInstruction }));
    else if (command === 'next') stdout(nextInstruction);
    else stdout([skippedGates ?? `autopilot: ${state.current_phase}`, nextInstruction].join('\n'));
    return;
  }

  if (command === 'advance') {
    const to = value(rest, '--to');
    if (to !== 'ralplan' && to !== 'ultragoal') throw new Error('--to must be ralplan or ultragoal.');
    const rawHandoff = value(rest, '--handoff-json');
    if (!rawHandoff) throw new Error('Missing --handoff-json.');
    const handoff = await jsonInput(rawHandoff);
    assertBoundHandoffIdentity(handoff, cwd, sessionId);
    const updated = await updateAutopilotPipelineState({
      ...handoff,
      active: true,
      current_phase: to,
    }, cwd, sessionId);
    if (json) stdout(JSON.stringify({ ok: true, state: updated, instruction: instruction(updated) }));
    else stdout(instruction(updated));
    return;
  }

  throw new Error(`Unknown autopilot command: ${command}\n${AUTOPILOT_HELP}`);
}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Add --handoff-json with an inline JSON object or a path to a JSON file: `omx autopilot advance --to ralplan --handoff-json handoff.json`
2. If building the command in a script, assert the handoff variable is non-empty before invoking

Example fix

// before
omx autopilot advance --to ultragoal
// after
omx autopilot advance --to ultragoal --handoff-json ./handoff.json

if (!args.includes('--handoff-json') && !args.some(a=>a.startsWith('--handoff-json='))) {
  throw new UsageError('advance requires --handoff-json');
}

try { await autopilotCommand(argv); } catch (e) { if (e.message === 'Missing --handoff-json.') promptForHandoffFile(); else throw e; }

When it happens

Trigger: Running `omx autopilot advance --to ralplan` without any --handoff-json flag; --handoff-json must be provided with either inline JSON or a file path.

Common situations: Assuming advance only needs the target phase, or a script that conditionally omits the handoff argument.

Related errors

• Missing --task.
• Usage: omx auth add <slot> [--device-auth|--with-api-key|--w
• Usage: omx auth use <slot>
• Missing value for ${flag}.
• --handoff-json must resolve to a JSON object.

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