pbakaus/impeccable · error

serve-question: --wait needs --key

Error message

serve-question: --wait needs --key

What it means

serve-question's --wait flag polls for an answer file for a previously started question, and it requires --key to identify which question to wait on. If --wait is given without --key, run() prints this message and exits 1 rather than guessing which question is meant.

Source

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

        }
    }
    let payload_path = a.arg("payload");
    let timeout_arg = js_number_arg(&a, "timeout", "900");
    let timeout_sec = if timeout_arg.is_finite() && timeout_arg >= 0.0 { timeout_arg } else { 900.0 };
    let idle_arg = js_number_arg(&a, "idle-grace", "600");
    let idle_grace_ms = (if idle_arg.is_finite() && idle_arg > 0.0 { idle_arg } else { 600.0 }) * 1000.0;
    let port_arg = js_number_arg(&a, "port", "0");
    let qdir = jsp::join(&[&cwd, ".impeccable", "questions"]);

    if a.has("schema") {
        io.out(&format!("{}\n", json_pretty(&schema_json())));
        io.out(&format!("{}\n", SCHEMA_NOTE));
        return 0;
    }

    if a.has("wait") {
        let Some(key) = a.arg("key") else {
            io.err("serve-question: --wait needs --key\n");
            return 1;
        };
        let poll_sec = js_number_arg(&a, "poll", "60");
        let deadline = now_ms() + poll_sec * 1000.0;
        let answered = || exists(&answer_file(&qdir, &key));
        let mut saw_close = false;
        while now_ms() < deadline {
            if answered() {
                break;
            }
            if exists(&flip_file(&qdir, &key)) {
                let _ = std::fs::remove_file(flip_file(&qdir, &key));
                io.out("BUILD PATH FLIPPED: comp (for this session only; never write it to settings). The table is still open and the page shows shimmer where the images will land: generate each open card’s comp into its declared path now, lead first, then collect the answer with --wait again. A card whose comp already exists needs nothing.\n");
                return 0;
            }
            if !is_alive(&qdir, &key) {
                io.out("serve-question: the question server is gone with no answer. This is a server failure, not a user decision: restart it with --start and the same payload, reopen the URL for the user, and wait again. Never proceed without their choice while their browser session is open.\n");
                return 2;

View on GitHub (pinned to 2bc2879276)

Solutions

  1. Pass the same --key value that was used with the original --start invocation.
  2. If the key is unknown, re-present the question with --start and a freshly generated key.
  3. In scripts, fail fast if the key variable is empty before calling serve-question.

Example fix

// before
serve-question --wait --poll 30
// after
serve-question --wait --key <key-from-start> --poll 30
Defensive patterns

Strategy: validation

Validate before calling

const args = process.argv.slice(2);
if (args.includes('--wait') && !args.includes('--key')) {
  throw new Error('serve-question --wait requires --key');
}

Type guard

null

Try / catch

const res = spawnSync('serve-question', args);
if (res.status === 1 && res.stderr.includes('--wait needs --key')) {
  // abort: re-invoke with the key from the original --start
}

Prevention

When it happens

Trigger: Invoking `serve-question --wait` (optionally with --poll) while omitting the `--key <key>` argument that identifies the question directory.

Common situations: Scripting the poll step after a session restart and losing the key; assuming --wait applies to the most recent question; shell variable holding the key is unset.

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