What causes "embed-prompt: --prompt or --prompt-file required " in pbakaus/impeccable?

Pass a non-empty prompt: `--prompt "your prompt text"`.

embed-prompt: --prompt or --prompt-file required

Error message

embed-prompt: --prompt or --prompt-file required

What it means

Guard at the top of embed_prompt's non-help path: after checking --prompt and --prompt-file (reading the file if given), the resolved prompt is either absent or empty after filtering. Fires when the user supplied neither flag, or the prompt-file's contents were blank.

Source

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

                0
            }
        }
    } else {
        let prompt = match arg_of("--prompt") {
            Some(p) => Some(p),
            None => match arg_of("--prompt-file") {
                Some(pf) if !pf.is_empty() => match std::fs::read(abs(&pf)) {
                    Ok(b) => Some(String::from_utf8_lossy(&b).into_owned()),
                    Err(e) => {
                        io.err(&format!("Error: {}\n", crate::util::node_read_error(&pf, &e)));
                        return 1;
                    }
                },
                _ => None,
            },
        };
        let Some(prompt) = prompt.filter(|p| !p.is_empty()) else {
            io.err("embed-prompt: --prompt or --prompt-file required\n");
            return 1;
        };
        let plen = utf16_len(&prompt);
        if png {
            // JS-PARITY: embed-prompt.mjs#641 finds IEND by walking the PNG
            // chunks (not buf.indexOf('IEND')) and reuses parsePng's chunk list
            // and prompt to rebuild the body idempotently.
            let (chunks, existing) = parse_png(&buf);
            let iend: i64 = chunks.iter().find(|c| &c.ty == b"IEND").map(|c| c.offset as i64).unwrap_or(-1);
            if iend < 8 {
                io.err("embed-prompt: malformed PNG\n");
                return 1;
            }
            let iend = iend as usize;
            let mut text_data = KEYWORD.to_vec();
            text_data.push(0);
            text_data.extend_from_slice(prompt.as_bytes());
            let text_chunk = png_chunk(b"tEXt", &text_data);

View on GitHub (pinned to 2bc2879276)

Solutions

Pass a non-empty prompt: `--prompt "your prompt text"`.
If using --prompt-file, confirm the file has content (wc -c prompt.txt).
Check the shell variable feeding --prompt is actually set (${VAR:?} guard in scripts).

Example fix

// before
impeccable embed-prompt --image out.png --prompt "$PROMPT"
// after
impeccable embed-prompt --image out.png --prompt "${PROMPT:?PROMPT is unset}"

Defensive patterns

Strategy: validation

Validate before calling

[ -n "$PROMPT" ] || [ -s "$PROMPT_FILE" ] || { echo "prompt required" >&2; exit 1; }

Type guard

const hasPrompt = (s) => typeof s === 'string' && s.trim().length > 0;

Prevention

Use ${VAR:?msg} to fail fast on unset prompt variables
Check prompt files are non-empty (wc -c) before passing
Never build CLI commands by naive string interpolation of optional args

When it happens

Trigger: Running embed-prompt in write mode with neither --prompt nor --prompt-file, passing --prompt "" (empty), or pointing --prompt-file at an empty file.

Common situations: Shell variable holding the prompt was unset (empty interpolation), a prompt-file created but never written by an upstream step, or forgetting the flag entirely.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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