pbakaus/impeccable · error

comp-diff: cannot read spec {sp}: {e}

Error message

comp-diff: cannot read spec {sp}: {e}

What it means

When `--spec <path>` is supplied, comp-diff reads the spec JSON file and parses it. This instance fires when the file read itself fails (missing file, permissions, path is a directory), reporting the path plus the io error and exiting 1. Note the same message is reused for JSON parse failure in the sibling arm.

Source

Thrown at crates/comp-verbs/src/comp_diff.rs:716

            io.err(&format!("comp-diff: cannot read comp {comp_path}: {e}\n"));
            return 1;
        }
    };
    let build = match read_png(io, build_path) {
        Ok(v) => v,
        Err(e) => {
            io.err(&format!("comp-diff: cannot read build {build_path}: {e}\n"));
            return 1;
        }
    };
    let mut spec: Option<Value> = None;
    let spec_path = arg(argv, "spec");
    if let Some(sp) = spec_path {
        match std::fs::read_to_string(resolve(io, sp)) {
            Ok(raw) => match serde_json::from_str::<Value>(&raw) {
                Ok(v) => spec = Some(v),
                Err(e) => {
                    io.err(&format!("comp-diff: cannot read spec {sp}: {e}\n"));
                    return 1;
                }
            },
            Err(e) => {
                io.err(&format!("comp-diff: cannot read spec {sp}: {e}\n"));
                return 1;
            }
        }
    }
    let default_out = {
        let d = Path::new(build_path).parent().map(|p| p.to_path_buf()).unwrap_or_default();
        d.join("diff").to_string_lossy().replace('\\', "/")
    };
    let out_dir = arg_or(argv, "out-dir", &default_out).to_string();
    let default_label = Path::new(build_path)
        .file_stem()
        .map(|s| s.to_string_lossy().to_string())
        .unwrap_or_default();

View on GitHub (pinned to 2bc2879276)

Solutions

  1. Verify the spec file exists at the given path (`ls -l <spec>`).
  2. Generate the spec first: `impeccable comp-spec --comp <png> --regions <json>` which writes .impeccable/build/spec.json.
  3. Use the default .impeccable/build/spec.json path or fix the relative path/working directory.
  4. Check read permissions on the spec file.

Example fix

// before
$ impeccable comp-diff --comp c.png --build b.png --spec ./specs.json
comp-diff: cannot read spec ./specs.json: No such file or directory
// after
$ impeccable comp-spec --comp c.png --regions regions.json
$ impeccable comp-diff --comp c.png --build b.png --spec .impeccable/build/spec.json
Defensive patterns

Strategy: try-catch

When it happens

Trigger: `--spec <path>` given a path that does not exist or cannot be read (permissions, is a directory); resolve(io, sp) points outside the workspace or to an unwritable/absent location.

Common situations: Typo'd spec path; spec not yet generated (comp-spec --regions never ran); running from a different working directory so the relative spec path misses; CI copying only images but not spec.json.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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