pbakaus/impeccable · error

build-phase: no state at {}; run build-phase.mjs start --com

Error message

build-phase: no state at {}; run build-phase.mjs start --comp <approved comp>

What it means

All build-phase subcommands other than `start` (status, advance, record, note, finish, etc.) require prior state created by `start`. load_state() returning None triggers this error naming the state file path, telling the user to run `build-phase.mjs start --comp <approved comp>` first, and exits 1.

Source

Thrown at crates/comp-verbs/src/build_phase.rs:1861

            }
        }
        let existing = load_state(io);
        if let Some(existing) = &existing {
            if !flag(argv, "reset") {
                io.out(&format!("build-phase: state exists (phase {}); pass --reset to start over\n", existing.get("phase").and_then(Value::as_str).unwrap_or("")));
                io.out(&format!("{}\n", render_status(io, existing)));
                return 0;
            }
        }
        let state = new_state(comp, breakpoint.as_deref(), arg(argv, "artifact"), direction);
        save_state(io, &state);
        io.out(&format!("{}\n", render_status(io, &state)));
        return 0;
    }
    let mut state = match load_state(io) {
        Some(s) => s,
        None => {
            io.err(&format!("build-phase: no state at {}; run build-phase.mjs start --comp <approved comp>\n", state_path()));
            return 1;
        }
    };
    match cmd {
        "status" => {
            if flag(argv, "json") {
                io.out(&format!("{}\n", util::json_pretty(&state)));
            } else {
                io.out(&format!("{}\n", render_status(io, &state)));
            }
            0
        }
        "scaffold" => {
            let Some(spec) = load_spec(&abs(io, SPEC_PATH)) else {
                io.err(&format!("build-phase: no spec at {SPEC_PATH}; run comp-spec.mjs first\n"));
                return 1;
            };
            let out = write_scaffold(io, &spec);

View on GitHub (pinned to 2bc2879276)

Solutions

1. Run `impeccable build-phase start --comp <approved comp png>` (or --direction <seed key>) to initialize state
2. Verify you are in the project directory that owns .impeccable/ state
3. Check the state file printed in the message exists and is valid JSON; restore from git if deleted

Example fix

// before
$ impeccable build-phase advance
// after
$ impeccable build-phase start --comp comps/hero-approved.png
$ impeccable build-phase advance

[ -f .impeccable/build-phase/state.json ] || { echo 'run build-phase start first'; exit 1; }
impeccable build-phase status

impeccable build-phase status --json || impeccable build-phase start --comp "$COMP"

When it happens

Trigger: Running `impeccable build-phase status|advance|record|note|finish|scaffold` (anything after the status render path that calls load_state) when no build-phase has been started in this project, or when the state file at state_path() was deleted.

Common situations: Fresh clone or new machine where the .impeccable state was never created; accidentally deleting .impeccable/ state; running in the wrong repo/directory; a `start` invocation that failed before persisting state.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• concept-seed: --candidate-count must be an integer from 5 to
• Unknown ignore-rule flag: ${arg}
• Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule
• overused-font is value-specific by default. Use ${IMPECCABLE
• --reason is not supported for ignore-file because detector.i

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