{"record":{"id":"482e6c00ae7079ff","repo":"pbakaus/impeccable","slug":"serve-question-start-needs-payload-file","errorCode":null,"errorMessage":"serve-question: --start needs --payload <file>\n","messagePattern":"serve-question: --start needs --payload <file>\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/context/src/serve_question.rs","lineNumber":319,"sourceCode":"        let ok = next_round.get(\"options\").and_then(|o| o.as_array()).map(|o| !o.is_empty()).unwrap_or(false);\n        if !ok {\n            io.err(\"serve-question: --update payload needs an options array; nothing was delivered. Fix the payload and rerun --update on the same key.\\n\");\n            return 1;\n        }\n        if !is_alive(&qdir, &key) {\n            io.err(\"serve-question: no live question server for that key; the page it served is gone too. Re-present the round with --start and a fresh key, or fall back to the structured question tool.\\n\");\n            return 2;\n        }\n        let delivered = next_file(&qdir, &key);\n        let _ = std::fs::copy(jsp::resolve(&cwd, &[&pp]), &delivered);\n        touch_now(&delivered);\n        io.out(\"next round delivered; the page reloads itself\\n\");\n        return 0;\n    }\n\n    if a.has(\"start\") {\n        let Some(pp) = payload_path.clone() else {\n            io.err(\"serve-question: --start needs --payload <file>\\n\");\n            return 1;\n        };\n        if let Err(msg) = read_json_file(&jsp::resolve(&cwd, &[&pp])) {\n            io.err(&format!(\"{}\\n\", msg));\n            return 1;\n        }\n        let _ = std::fs::create_dir_all(&qdir);\n        let key = a.arg(\"key\").unwrap_or_else(random_key);\n        let log_file = jsp::join(&[&qdir, &format!(\"{}.log\", key)]);\n        let log = std::fs::OpenOptions::new().append(true).create(true).open(&log_file);\n        let exe = std::env::current_exe().map(|p| p.to_string_lossy().into_owned()).unwrap_or_else(|_| \"impeccable\".to_string());\n        let mut child_args: Vec<String> = vec![\n            \"serve-question\".into(),\n            \"--payload\".into(),\n            pp.clone(),\n            \"--detached-serve\".into(),\n            \"--key\".into(),\n            key.clone(),","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/pbakaus/impeccable/blob/2bc2879276c1f321a53c4ca99d3371e411329b52/crates/context/src/serve_question.rs#L301-L337","documentation":"--start launches a live question page but requires --payload <file> pointing at the JSON describing the question (question text and options). Without it, run() prints this message and exits 1 before creating any question directory or server.","triggerScenarios":"Invoking `serve-question --start` (with or without --key) but omitting the `--payload <file>` argument.","commonSituations":"First-time users assuming a default question payload; scripts where the payload path variable is unset; copy-pasting a start command and dropping the payload argument.","solutions":["Pass --payload with the path to a JSON file containing the question and a non-empty options array.","Create the payload JSON first if it does not exist.","Guard the payload path in scripts before invoking serve-question."],"exampleFix":"// before\nserve-question --start --key q-1\n// after\nserve-question --start --key q-1 --payload question.json","handlingStrategy":"validation","validationCode":"if (args.includes('--start') && !args.includes('--payload')) {\n  throw new Error('serve-question --start requires --payload <file>');\n}","typeGuard":"null","tryCatchPattern":"const res = spawnSync('serve-question', args);\nif (res.status === 1 && res.stderr.includes('--start needs --payload')) {\n  // write the question payload JSON, then retry --start\n}","preventionTips":["Always generate the payload JSON before starting the server","Wrap --start in a helper whose signature requires the payload path","Check the payload file exists before invoking"],"tags":["cli","argument-validation","startup"],"backgroundTag":"missing-required-flag","analyzedSha":"2bc2879276c1f321a53c4ca99d3371e411329b52","analyzedAt":"2026-09-08T04:51:14.109Z","contentChangedAt":"2026-09-08T04:51:14.109Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}