pbakaus/impeccable · error

serve-question: --update payload needs an options array; not

Error message

serve-question: --update payload needs an options array; nothing was delivered. Fix the payload and rerun --update on the same key.

What it means

After the --update payload is read, run() checks that it contains a non-empty options array. If the payload lacks options or has an empty options array, the round is not delivered: this message is printed, exit code 1, and the caller is told to fix the payload and rerun --update on the same key.

Source

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

        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;
        }
        let delivered = next_file(&qdir, &key);
        let _ = std::fs::copy(jsp::resolve(&cwd, &[&pp]), &delivered);
        touch_now(&delivered);
        io.out("next round delivered; the page reloads itself\n");
        return 0;
    }

    if a.has("start") {
        let Some(pp) = payload_path.clone() else {
            io.err("serve-question: --start needs --payload <file>\n");
            return 1;
        };

View on GitHub (pinned to 2bc2879276)

Solutions

1. Add a non-empty 'options' array to the payload JSON and re-run --update with the same --key.
2. Check upstream data generation if options came out empty.
3. Validate payload structure (options present, array, length > 0) before invoking.

Example fix

// before
{"question":"Next step?"}
// after
{"question":"Next step?","options":["Retry","Abort"]}

const payload = JSON.parse(fs.readFileSync(payloadPath, 'utf8'));
if (!Array.isArray(payload.options) || payload.options.length === 0) {
  throw new Error('payload.options must be a non-empty array');
}

const hasOptions = (p) => Array.isArray(p?.options) && p.options.length > 0;

if (res.status === 1 && res.stderr.includes('needs an options array')) {
  // regenerate/repair the payload, keep the SAME --key, and rerun --update
}

When it happens

Trigger: --update payload JSON that has no 'options' key, has options as a non-array, or has an empty options array.

Common situations: Hand-written payloads missing the options field; generators producing empty option lists when upstream data is missing; reusing a payload template with placeholders unfilled.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• invalid session id: ${id}
• build-phase: finish --disposition ship|fix|rebuild|recapture
• comp-spec: cannot read regions {rf}: {e}
• embed-prompt: malformed PNG
• Unknown command: {}

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