Exit Codes for Image Conversion Jobs

Image conversion jobs should not be judged by console text alone. Shell scripts, CI pipelines, and agent workflows need a stable signal that says whether the command succeeded, failed completely, partially failed, or needs a different kind of handling. That signal is the process exit code.

GetWebP CLI uses semantic exit codes so automation can react without parsing human-readable logs. This is especially useful in CI, where a conversion job might process many files and produce a structured JSON or NDJSON report.

This is also a place where weak automation content causes real damage. A blog post that says "check for non-zero" or copies an old exit-code table can make a release job retry the wrong failure, ignore a partial conversion, or send a developer to fix licensing when the actual issue was invalid command syntax. Treat the numeric table as part of the integration contract.

Know the Core Meanings#

For the current GetWebP CLI, the important exit codes are listed in the LLM context document:

0    success
1    generic error
2    usage error
3    partial failure
4    auth error
5    network error
6    free-tier limit reached
75   license revoked or expired during a long-running session
76   disk full during a watch session after retry budget is exhausted
130  interrupted with Ctrl+C
143  terminated with SIGTERM

These codes should drive different decisions. A network error may be retryable. A partial failure means some files may have succeeded and others need review. A usage error needs a script fix. An auth error needs license or device attention, not another blind retry.

Treat Partial Failure Separately#

Exit code 3 is the one many scripts handle poorly. It means at least one file failed while others succeeded. That is different from total failure.

For example, a batch might convert 98 images and fail on 2 corrupt files. The pipeline should not pretend everything is fine, but it may also be useful to keep the successful outputs and inspect the failed files from the JSON report.

A good script can warn or fail based on policy:

set +e
getwebp ./images -o ./dist --json > conversion.ndjson
code=$?
set -e

if [ "$code" -eq 3 ]; then
  echo "Partial failure: inspect conversion.ndjson" >&2
  exit 1
fi

For production releases, failing on partial conversion is often the safer default.

The distinction matters because successful outputs may already have been written. Your cleanup policy should be explicit: keep successful outputs for inspection, remove the output directory before retry, or rerun only the failed inputs after fixing them.

Retry Only Retryable Cases#

Not every non-zero exit code deserves a retry. Retrying an invalid command or expired license wastes CI time. Retrying a network timeout may make sense.

Example:

set +e
getwebp ./images -o ./dist --json > conversion.ndjson
code=$?
set -e

case "$code" in
  0)
    echo "Image conversion succeeded"
    ;;
  2)
    echo "Usage error: fix the getwebp command or flags" >&2
    exit 2
    ;;
  3)
    echo "Some files failed: inspect the report" >&2
    exit 1
    ;;
  4)
    echo "Auth error: check license secret, expiry, revocation, or device limit" >&2
    exit 4
    ;;
  5)
    echo "Network error: retry the job or run a backoff step" >&2
    exit 5
    ;;
  6)
    echo "Free-tier limit reached: conversion was truncated" >&2
    exit 6
    ;;
  75)
    echo "License became invalid during a long-running session" >&2
    exit 75
    ;;
  76)
    echo "Disk full during image conversion watch workflow" >&2
    exit 76
    ;;
  130|143)
    echo "Job was interrupted or terminated" >&2
    exit "$code"
    ;;
  *)
    echo "Image conversion failed with exit code $code" >&2
    exit "$code"
    ;;
esac

This keeps automation intentional. The pipeline does not treat every failure as the same problem.

set +e is deliberate in these examples. If a shell script runs with set -e, the script can exit before it records $?, which defeats the point of branching by exit code.

Pair Exit Codes With JSON Output#

Exit codes tell you the category of result. JSON or NDJSON output tells you the details. Use both.

The exit code can decide whether the pipeline continues. The report can identify which files failed, what error code appeared, and what outputs were written. With --json, GetWebP writes structured events on stdout; human messages and warnings are separate from that stream. The JSON output reference documents convert.completed, convert.truncated, convert.failed, and the results[] fields used in CI checks.

This combination is better than scraping console text because it gives both a simple process-level decision and a machine-readable record for debugging.

To print failed files from a partial conversion:

jq -r '
  select(.type == "convert.completed")
  | .data.results[]
  | select(.status == "error")
  | "\(.file): \(.error)"
' conversion.ndjson >&2

To fail when the Free plan truncated the run:

if jq -e 'select(.type == "convert.truncated")' conversion.ndjson >/dev/null; then
  jq -r '
    select(.type == "convert.truncated")
    | "Processed \(.data.processed); skipped \(.data.skipped)"
  ' conversion.ndjson >&2
  exit 6
fi

To check the success count without reading terminal text:

jq -e '
  select(.type == "convert.completed")
  | .data.failedCount == 0
' conversion.ndjson >/dev/null

Do not parse progress bars, colored messages, or warning text. Those are for people. The NDJSON stream is for scripts.

Understand Precedence#

Long-running and multi-file commands can have more than one interesting condition. GetWebP resolves the final process code by precedence:

signal shutdown
mid-session license invalidation
free-tier truncation
mixed per-file success and failure
startup, usage, auth, network, or generic failures

In practical terms:

• 130 or 143 should be treated as job control, not image quality.
• 75 means the license changed during a long-running session; rerunning blindly can loop until activation is fixed.
• 6 means the run did not cover every file, even if the processed files were valid.
• 3 means at least one output may be usable, but release policy should decide whether to keep or discard it.
• 2 means the command itself is wrong; changing input images will not fix it.

If zero files match, the current default is success. If your CI policy requires at least one processed image, enforce that from the report by checking .data.total or from your own file discovery step.

Decide the CI Policy Up Front#

Before adding image conversion to CI, define the policy:

• should partial failure fail the build?
• should network errors retry?
• should missing input be treated as success or failure?
• should Free-plan truncation block the merge?
• should successful outputs be committed, uploaded, or only reported?
• should outputs created before a partial failure be kept or deleted?
• who reviews visual quality after the mechanical check passes?

CI should encode those choices instead of leaving each contributor to infer them from logs.

GitHub's Actions documentation explains workflow behavior and failure handling. Google's WebP documentation provides background on the image format being generated.

Avoid Treating Exit 0 as Visual Approval#

Exit code 0 means the command completed successfully. It does not mean the images look good. A conversion can succeed mechanically while producing a screenshot that is too blurry or a product image with visible artifacts.

Use exit codes for automation health. Use visual review for image quality. The two checks should support each other, not replace each other.

This matters most for:

• product gallery zoom images
• screenshots with small UI text
• hero images above the fold
• transparent logos and icons
• photos where skin tone, fabric texture, or brand color matters

Make Failures Useful#

When a job fails, print a short next step:

Exit 2: usage error. Fix the command flags or missing path.
Exit 3: some files failed. Open conversion.ndjson and inspect failed inputs.
Exit 4: activation or license problem. Check the CI secret and device binding.
Exit 5: network error. Retry with backoff or check firewall rules.
Exit 6: Free-tier limit reached. The run was truncated before all files were processed.
Exit 75: license changed during a long-running session. Re-authenticate before rerunning.
Exit 76: disk full. Free space and rerun the job.

Good failure messages reduce wasted time in pull requests and release builds.

Exit codes are small, but they make image conversion jobs much easier to operate. They let CI distinguish a bad input file from a license issue, a network problem from a visual review task, and a complete success from a partial one.