What causes "serve-question: --update needs --key and --payload " in pbakaus/impeccable?

Supply both --key (from --start) and --payload pointing at a JSON file.

serve-question: --update needs --key and --payload

Error message

serve-question: --update needs --key and --payload

What it means

The --update flag delivers a follow-up round to a live question page, and it needs both --key (which question) and --payload (the JSON file describing the next round). If either is missing, run() prints this message and exits 1.

Source

Thrown at crates/context/src/serve_question.rs:291

        let Some(key) = a.arg("key") else {
            io.err("serve-question: --stop needs --key\n");
            return 1;
        };
        if let Some(state) = read_state(&qdir, &key) {
            if let Some(pid) = state.get("pid").and_then(|p| p.as_f64()) {
                kill_pid(pid as i64);
            }
        }
        let _ = std::fs::remove_file(answer_file(&qdir, &key));
        let _ = std::fs::remove_file(state_file(&qdir, &key));
        io.out("stopped\n");
        return 0;
    }

    if a.has("update") {
        let key = a.arg("key");
        let (Some(key), Some(pp)) = (key, payload_path.clone()) else {
            io.err("serve-question: --update needs --key and --payload\n");
            return 1;
        };
        let next_round = match read_json_file(&jsp::resolve(&cwd, &[&pp])) {
            Ok(v) => v,
            Err(msg) => {
                io.err(&format!("{}\n", msg));
                return 1;
            }
        };
        let ok = next_round.get("options").and_then(|o| o.as_array()).map(|o| !o.is_empty()).unwrap_or(false);
        if !ok {
            io.err("serve-question: --update payload needs an options array; nothing was delivered. Fix the payload and rerun --update on the same key.\n");
            return 1;
        }
        if !is_alive(&qdir, &key) {
            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");
            return 2;
        }

View on GitHub (pinned to 2bc2879276)

Solutions

Supply both --key (from --start) and --payload pointing at a JSON file.
Validate that both shell variables are non-empty before invoking.
If the payload is missing, write the next-round JSON (with an options array) first, then update.

Example fix

// before
serve-question --update --key q-123
// after
serve-question --update --key q-123 --payload round2.json

Defensive patterns

Strategy: validation

Validate before calling

if (args.includes('--update') && !(args.includes('--key') && args.includes('--payload'))) {
  throw new Error('serve-question --update requires both --key and --payload');
}

Type guard

null

Try / catch

const res = spawnSync('serve-question', args);
if (res.status === 1 && res.stderr.includes('--update needs --key and --payload')) {
  // re-invoke with both arguments supplied
}

Prevention

Build the update command from a helper that always takes (key, payloadPath)
Check both values are non-empty strings before spawning
Keep --start and --update argument shapes symmetric in scripts

When it happens

Trigger: Invoking `serve-question --update` with neither or only one of `--key <key>` and `--payload <file>`.

Common situations: Multi-round question flows where the second call forgets the payload path; scripts templating only part of the command; refactoring --start calls to --update without carrying the payload argument over.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/9399d14ebfe471a3. Report an issue: GitHub.