Exit codes & errors

imgsqz aims to fail clearly and predictably — useful in scripts and CI.

Exit codes

Code	When
0	Every input was processed successfully.
1	One or more inputs failed, or a usage/validation error occurred.

Because a failed batch exits non-zero, you can gate CI steps on it:

imgsqz public/img/*.png -f webp -q 75 --quiet && echo "All optimized ✅"

Per-file errors

Inside a batch, each failing file prints to stderr and processing continues with the next file:

✗ broken.png: Input file not found: /abs/path/broken.png

Common per-file messages:

Message	Cause	Fix
Input file not found: <path>	The path doesn’t exist	Check the path / glob; ensure the shell expanded it
Not a file: <path>	The path is a directory	Point at files, not folders (dir/*.png, not dir)
Refusing to overwrite the input file. Use --replace …	Output path would equal the input	Add --replace, or set a different -o / keep the timestamp
Unsupported format "<x>". Choose from: …	Bad -f value	Use jpg, jpeg, png, webp, avif, or tiff
sharp decode errors	Truly corrupt/unreadable source	Verify the file opens in an image viewer

Note

imgsqz opens sources with failOn: "none", so minor corruption is tolerated and the image still processes. Only unrecoverable files raise a decode error.

Usage / validation errors

These stop the command immediately (before processing):

Message	Cause	Fix
--output can only be used with a single input file.	-o with 2+ inputs	Use a shell loop or drop -o
error: option '-q, --quality <n>' argument '...' is invalid. Must be an integer between 1 and 100.	Quality out of range / not an integer	Pass an integer 1–100
error: option '--width <px>' argument '...' is invalid. Must be a positive integer.	Non-positive / non-integer size	Pass a positive integer
error: option '-f, --format <format>' argument '...' is invalid.	Format not in the allowed list	Choose a supported format
error: missing required argument 'input'	No input given	Provide at least one image path

On a usage error, imgsqz also prints the help text (showHelpAfterError) so you can see valid options immediately.

Stray temp files

--replace writes <name>.imgsqz.tmp before renaming over the original. If a run is killed mid-write, that temp file may remain — it’s safe to delete, and your original is untouched:

rm *.imgsqz.tmp

Debugging tips

• Quote globs that your shell might mangle, or let the shell expand them intentionally — imgsqz *.png relies on shell expansion.
• Check node --version is ≥ 18 if the CLI won’t start.
• Run a single file first to isolate a failing image in a large batch.
• Drop --quiet to see the full per-file report while diagnosing.