{"record":{"id":"8c68a2d08ec64799","repo":"Yeachan-Heo/oh-my-codex","slug":"missing-handoff-json","errorCode":null,"errorMessage":"Missing --handoff-json.","messagePattern":"Missing --handoff-json\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/cli/autopilot.ts","lineNumber":147,"sourceCode":"  }\n\n  const state = await readAutopilot(cwd, sessionId);\n  if (!state) throw new Error('No Autopilot state found. Run `omx autopilot start --task <text>` first.');\n\n  if (command === 'status' || command === 'next') {\n    const nextInstruction = instruction(state);\n    const skippedGates = skippedGateReport(state as unknown as Record<string, unknown>);\n    if (json) stdout(JSON.stringify({ state, instruction: nextInstruction }));\n    else if (command === 'next') stdout(nextInstruction);\n    else stdout([skippedGates ?? `autopilot: ${state.current_phase}`, nextInstruction].join('\\n'));\n    return;\n  }\n\n  if (command === 'advance') {\n    const to = value(rest, '--to');\n    if (to !== 'ralplan' && to !== 'ultragoal') throw new Error('--to must be ralplan or ultragoal.');\n    const rawHandoff = value(rest, '--handoff-json');\n    if (!rawHandoff) throw new Error('Missing --handoff-json.');\n    const handoff = await jsonInput(rawHandoff);\n    assertBoundHandoffIdentity(handoff, cwd, sessionId);\n    const updated = await updateAutopilotPipelineState({\n      ...handoff,\n      active: true,\n      current_phase: to,\n    }, cwd, sessionId);\n    if (json) stdout(JSON.stringify({ ok: true, state: updated, instruction: instruction(updated) }));\n    else stdout(instruction(updated));\n    return;\n  }\n\n  throw new Error(`Unknown autopilot command: ${command}\\n${AUTOPILOT_HELP}`);\n}\n","sourceCodeStart":129,"sourceCodeEnd":162,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/cli/autopilot.ts#L129-L162","documentation":"The `autopilot advance` command requires a handoff payload in addition to --to. This error fires when --handoff-json is absent from the arguments.","triggerScenarios":"Running `omx autopilot advance --to ralplan` without any --handoff-json flag; --handoff-json must be provided with either inline JSON or a file path.","commonSituations":"Assuming advance only needs the target phase, or a script that conditionally omits the handoff argument.","solutions":["Add --handoff-json with an inline JSON object or a path to a JSON file: `omx autopilot advance --to ralplan --handoff-json handoff.json`","If building the command in a script, assert the handoff variable is non-empty before invoking"],"exampleFix":"// before\nomx autopilot advance --to ultragoal\n// after\nomx autopilot advance --to ultragoal --handoff-json ./handoff.json","handlingStrategy":"validation","validationCode":"if (!args.includes('--handoff-json') && !args.some(a=>a.startsWith('--handoff-json='))) {\n  throw new UsageError('advance requires --handoff-json');\n}","typeGuard":null,"tryCatchPattern":"try { await autopilotCommand(argv); } catch (e) { if (e.message === 'Missing --handoff-json.') promptForHandoffFile(); else throw e; }","preventionTips":["Treat --to and --handoff-json as a required pair in scripts","Default the handoff to a known file path in wrappers"],"tags":["cli","missing-argument","autopilot"],"backgroundTag":"missing-required-flag","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}