pbakaus/impeccable · error

build-phase: no spec at {SPEC_PATH}; run comp-spec.mjs first

Error message

build-phase: no spec at {SPEC_PATH}; run comp-spec.mjs first

What it means

The `build-phase scaffold` subcommand reads a comp spec file (SPEC_PATH) produced by comp-spec.mjs. If load_spec() cannot load/parse the spec, it prints 'build-phase: no spec at {SPEC_PATH}; run comp-spec.mjs first' and exits 1.

Source

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

    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);
            let bp = state.get("breakpoint").and_then(Value::as_str).map(String::from).unwrap_or_else(|| {
                let w = spec.pointer("/compSize/width").and_then(Value::as_i64).unwrap_or(0);
                let h = spec.pointer("/compSize/height").and_then(Value::as_i64).unwrap_or(0);
                format!("{w}x{h}")
            });
            io.out(&format!("SCAFFOLD {}\n", out.dir));
            io.out(&format!("  {}   one custom property set per region (--r-<id>-x/y/w/h in % of the comp; --r-<id>-cap, --r-<id>-font, --r-<id>-weight where measured); bind these to your own markup\n", out.css));
            io.out(&format!("  {}  a reference page: every region positioned at its box inside a {bp} frame, plates placed with object-fit: contain, text slots at the measured cap height in the ranked face\n", out.html));
            io.out("  The reference is a check, not the page: keep your own semantic structure and bind the numbers to it (an element per region, its box from the properties). Overlapping boxes are overlapping boxes. What the gate reads is pixels; a page that lands each region at its box passes whatever markup it uses.\n");
            0
        }
        "note" => {
            let text = argv[1..].iter().filter(|a| !a.starts_with("--")).cloned().collect::<Vec<_>>().join(" ");
            let phase = state.get("phase").and_then(Value::as_str).unwrap_or("").to_string();
            if let Some(notes) = state.pointer_mut(&format!("/phases/{phase}/notes")).and_then(|v| v.as_array_mut()) {

View on GitHub (pinned to 2bc2879276)

Solutions

  1. Run the comp-spec step (comp-spec.mjs) first to generate the spec at SPEC_PATH
  2. Verify the spec file exists at the path named in the message and is valid JSON
  3. Re-generate the spec if it was hand-edited or corrupted

Example fix

// before
$ impeccable build-phase scaffold
// after
$ npx comp-spec.mjs   # generate the spec first
$ impeccable build-phase scaffold
Defensive patterns

Strategy: validation

Validate before calling

[ -f "$SPEC_PATH" ] || { echo 'run comp-spec.mjs first'; exit 1; }
impeccable build-phase scaffold

Try / catch

impeccable build-phase scaffold || { echo 'missing spec; generating...'; npx comp-spec.mjs && impeccable build-phase scaffold; }

Prevention

When it happens

Trigger: Running `impeccable build-phase scaffold` before the comp-spec step was run, or when the spec file at SPEC_PATH is missing or not valid loadable spec JSON.

Common situations: Skipping the comp-spec step of the workflow; running scaffold in a directory where comp-spec output was never generated; a corrupted or hand-edited spec file that fails to load.

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

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