What causes "comp-diff: cannot read build {build_path}: {e} " in pbakaus/impeccable?

Verify the build PNG path exists and is readable.

comp-diff: cannot read build {build_path}: {e}

Error message

comp-diff: cannot read build {build_path}: {e}

What it means

Same read/decode guard as the comp image, but applied to the `--build` PNG — the screenshot of the built page being compared against the comp. On read or decode failure it prints the build path plus the io error and exits 1.

Source

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

/// `impeccable comp-diff --comp <png> --build <png> ...`
pub fn run(argv: &[String], io: &mut Io) -> i32 {
    let comp_path = arg(argv, "comp");
    let build_path = arg(argv, "build");
    let (Some(comp_path), Some(build_path)) = (comp_path, build_path) else {
        io.err("usage: comp-diff.mjs --comp <png> --build <png> [--spec spec.json] [--out-dir dir] [--align top|stretch] [--label name] [--threshold 0.75] [--json]\n");
        return 1;
    };
    let comp = match read_png(io, comp_path) {
        Ok(v) => v,
        Err(e) => {
            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;
            }

View on GitHub (pinned to 2bc2879276)

Solutions

Verify the build PNG path exists and is readable.
Confirm the format with `file <path>` — must be PNG image data.
Re-run the screenshot capture step that produces the build image.
Check that the pipeline that generates the build PNG ran before comp-diff.

Example fix

// before
$ impeccable comp-diff --comp ./comp.png --build ./old-shot.png
comp-diff: cannot read build ./old-shot.png: No such file or directory
// after
$ bun run screenshots && impeccable comp-diff --comp ./comp.png --build ./.impeccable/build/page.png

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync, readFileSync } from 'node:fs';
if (!existsSync(buildPath)) throw new Error(`build screenshot missing: ${buildPath}`);
const magic = readFileSync(buildPath).subarray(0, 8);
if (!magic.equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
  throw new Error(`${buildPath} is not a valid PNG`);
}

Type guard

function isPngFile(p) {
  try { return readFileSync(p).subarray(0, 8).toString('hex') === '89504e470d0a1a0a'; }
  catch { return false; }
}

Try / catch

try {
  runSync('impeccable', ['comp-diff', '--comp', comp, '--build', build]);
} catch (e) {
  if (/cannot read build/.test(e.stderr ?? '')) {
    console.error(`Build screenshot unreadable: ${build}. Re-run the screenshot step.`);
    process.exit(1);
  }
  throw e;
}

Prevention

Make the screenshot capture step a hard prerequisite in CI (fail the job if it produces no file).
Use deterministic output paths for build screenshots.
Check file size > 0 and PNG magic before comparing.
Re-download CI artifacts completely before comparing.

When it happens

Trigger: `--build <path>` points at a nonexistent file, an unreadable path, a non-PNG format, or a corrupted/truncated PNG; the built screenshot step failed silently upstream and produced no file.

Common situations: The screenshot/dev-server capture step failed or wrote to a different directory; CI artifact wasn't downloaded; stale script referencing an old output filename; image saved in another format.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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