pbakaus/impeccable · error

embed-prompt: image file required

Error message

embed-prompt: image file required

What it means

The embed/write mode of `embed-prompt` requires an image file that exists on disk (passed via --image or a positional). If the flag is absent, empty, or points at a nonexistent path, the CLI prints this and exits 1.

Source

Thrown at crates/context/src/embed_prompt.rs:238

        }
        let mut missing = 0;
        for r in &rasters {
            if prompt_of(&abs(r)).is_none() {
                io.out(&format!("MISSING: {}\n", r));
                missing += 1;
            }
        }
        io.out(&format!(
            "SCAN: {} raster{}, {} missing\n",
            rasters.len(),
            if rasters.len() == 1 { "" } else { "s" },
            missing
        ));
        return if missing > 0 { 3 } else { 0 };
    }

    let Some(file) = file.filter(|f| exists(&abs(f))) else {
        io.err("embed-prompt: image file required\n");
        return 1;
    };
    let file_abs = abs(&file);
    let buf = std::fs::read(&file_abs).unwrap_or_default();
    let ty = image_type(&buf);
    let png = ty == Some(ImageType::Png);
    let jpeg = ty == Some(ImageType::Jpeg);
    let sidecar = format!("{}.json", file);
    let sidecar_abs = format!("{}.json", file_abs);

    if read_mode {
        let prompt = read_prompt(&file_abs, &buf);
        match prompt {
            None => {
                io.err("embed-prompt: no embedded prompt found\n");
                2
            }
            Some(p) => {

View on GitHub (pinned to 2bc2879276)

Solutions

1. Pass an existing image file: `impeccable embed-prompt --image out.png --prompt "..."`.
2. Verify the path exists (ls) and use an absolute path if unsure about cwd.
3. Ensure the image-producing step (e.g. generate-image --out) ran before the embed step.

Example fix

// before
impeccable embed-prompt --prompt "a cat" --out out.png
// after
impeccable embed-prompt --image out.png --prompt "a cat"

[ -n "$IMAGE" ] && [ -f "$IMAGE" ] || { echo "image file required" >&2; exit 1; }

const hasImage = (p) => typeof p === 'string' && p.length > 0 && fs.existsSync(p);

When it happens

Trigger: Running `impeccable embed-prompt` (write mode) without --image, with an empty --image value, or with a path that does not exist relative to cwd.

Common situations: Forgot to pass --image while only providing --prompt, typoed image path, or referencing an image generated in a different directory in CI.

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

• Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule
• Pass a glob, e.g. ${IMPECCABLE_COMMAND} hooks ignore-file "s
• Pass a rule id and value, e.g. ${IMPECCABLE_COMMAND} hooks i
• usage: comp-diff.mjs --comp <png> --build <png> [--spec spec
• usage: comp-spec.mjs --comp <png> (--grid | --regions <json>

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