What causes "serve-question: --stop needs --key " in pbakaus/impeccable?

Re-run with the exact --key used at --start time.

serve-question: --stop needs --key

Error message

serve-question: --stop needs --key

What it means

The --stop flag shuts down a running question server by killing the recorded PID, which requires --key to locate the state file holding that PID. Without --key, run() prints this message and exits 1 instead of stopping an arbitrary question server.

Source

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

            return 3;
        }
        let collected = safe_read(&answer_file(&qdir, &key)).unwrap_or_default();
        let collected = crate::util::js_trim(&collected).to_string();
        print_answer(io, &collected);
        let mut keeps_open = false;
        if let Ok(p) = serde_json::from_str::<Value>(&collected) {
            keeps_open = p.get("optionId").and_then(|v| v.as_str()) == Some("reroll") || p.get("followup") == Some(&Value::Bool(true));
        }
        let _ = std::fs::remove_file(answer_file(&qdir, &key));
        if !keeps_open {
            let _ = std::fs::remove_file(state_file(&qdir, &key));
        }
        return 0;
    }

    if a.has("stop") {
        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;

View on GitHub (pinned to 2bc2879276)

Solutions

Re-run with the exact --key used at --start time.
If the key is lost, list the question directories under the qdir to recover candidate keys.
As a last resort, kill the server process manually and remove the stale state file.

Example fix

// before
serve-question --stop
// after
serve-question --stop --key <key-from-start>

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

null

Try / catch

const res = spawnSync('serve-question', args);
if (res.status === 1 && res.stderr.includes('--stop needs --key')) {
  // recover the key from the qdir state files, then retry
}

Prevention

Store the key alongside the PID when starting the question
Enumerate qdir state files to recover keys before stopping
Never issue a bare --stop in shared scripts

When it happens

Trigger: Invoking `serve-question --stop` without the `--key <key>` argument identifying the question whose server should be terminated.

Common situations: Cleanup scripts that lost track of the key between sessions; trying to stop 'the' question server when several keys may be live; copy-pasting a stop command without editing the key placeholder.

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/0ded400c5544a3bb. Report an issue: GitHub.