Troubleshooting Corrupt or Unsupported Image Inputs

Most image conversion failures are not mysterious. A file may be renamed with the wrong extension, partially downloaded, locked by another process, unsupported by the converter, or stored in a folder the command cannot write to. The hard part is not the failure itself. The hard part is making sure a batch workflow reports the failure clearly enough that a person can fix the right file.

When a conversion job fails on corrupt or unsupported inputs, resist the urge to rerun the same command repeatedly. Slow down, isolate the file, verify what it really is, and decide whether the workflow should skip it, repair it, or process it with a more specific tool.

"Check the file type" or "reinstall the converter" does not preserve the evidence a batch pipeline needs. A diagnosis should keep the failing path, command, exit code, per-file error, and enough detail to separate unsupported inputs, corrupt sources, permission problems, and partial failures.

Start With the Exact Failed Path#

The first fact to preserve is the exact path that failed. In a folder with hundreds of images, a vague message like "unsupported image" does not identify the file. Structured output, NDJSON logs, or a saved terminal transcript should identify the input path and the error category.

GetWebP CLI can process common web image inputs such as .jpg, .jpeg, .png, .bmp, .webp, .heic, .heif, and .avif; the supported input and output matrix is documented in the CLI commands reference. If the file is outside that list, the right fix may be to exclude it rather than force it through the same pipeline.

Once you have the path, test that single file by itself. A one-file run removes noise from the batch job:

getwebp ./assets/problem-file.png --json

If the single-file run fails the same way, you can focus on the input. If it succeeds, the batch failure may involve output paths, permissions, concurrency, or a surrounding script.

Check Whether the Extension Is Honest#

File extensions are labels, not proof. A file named banner.jpg may actually be a PNG. A file named logo.webp may be a failed HTML download saved with an image extension. A CMS export may contain placeholders or error pages beside real assets.

Use an image viewer, operating system inspector, or file identification tool to confirm the format. If the file cannot be opened anywhere, the converter is probably not the first problem.

Useful references for format expectations:

• MDN image file type and format guide
• Google WebP documentation

Do not build a workflow that trusts extensions alone. A safer batch job treats unsupported or mismatched files as reportable exceptions, then moves on according to the project's failure policy.

Look for Truncated or Placeholder Files#

Corruption often comes from incomplete transfers. A download may stop early. A cloud storage client may leave a placeholder file that has not been hydrated locally. A ZIP extraction may fail halfway. A design export may write a zero-byte file after an interrupted process.

Check the basics:

• Is the file size zero?
• Does the image open in a normal viewer?
• Are dimensions available?
• Was the file recently copied or synced?
• Does re-downloading the source fix it?

For team workflows, store originals separately from converted outputs. If a source file is corrupt, it should be replaced from the authoritative source rather than repaired by guessing. If the only available copy is corrupt, document that before excluding it from conversion.

Separate Unsupported From Broken#

Unsupported and broken are different problems.

An unsupported file may be valid, but outside the converter's input list. Examples include specialized camera RAW formats, layered design files, PDFs, SVGs, or proprietary exports. These files may need a design tool, a raster export step, or a separate pipeline.

A broken file is expected to be supported but cannot be decoded correctly. Examples include truncated JPEGs, damaged PNG chunks, invalid headers, or files that contain HTML error pages.

Treating both cases as "conversion failed" loses information. In reports, label them separately when possible:

• unsupported_format
• decode_failed
• permission_denied
• write_failed
• skipped_existing

Those labels are review categories, not a substitute for the converter's actual output. When using GetWebP with --json, preserve the per-file status and error fields described in the JSON output reference, then add a human review category beside them. That gives automation the raw evidence and gives maintainers a short decision label.

Check Permissions and Output Paths#

Sometimes the input is fine and the output path is the problem. A converter may fail because the destination folder does not exist, the process lacks write permission, a file already exists, or a read-only volume is mounted in CI.

Confirm:

• the input path is readable
• the output directory exists or can be created
• the process can write to the destination
• the output filename is valid for the operating system
• no existing file is locked by another process

If the job writes outputs beside originals, permissions need to be correct in the source tree. If the job writes to a separate output folder, the folder structure should be created intentionally. Mirrored output directories are cleaner than ad hoc string replacements because the relationship between source and output stays visible.

Handle Partial Failure Honestly#

Batch image conversion should distinguish complete success from partial success. If 199 files convert and 1 file fails, the run is not a clean success. It may still produce useful outputs, but the report should say what happened.

In current GetWebP CLI workflows, a partial failure is represented by exit code 3: at least one file succeeded and at least one file failed. Exit code 2 is reserved for usage errors such as invalid arguments. Automation should preserve that distinction. A CI job may choose to fail the build, attach a report, or allow the build to continue for non-critical images. The key is that the decision is explicit.

Avoid scripts that hide failed files because "most images converted." That habit creates broken references later, especially when a second step rewrites image paths under the assumption that every output exists.

Build a Quarantine Folder#

For recurring projects, create a quarantine folder for failed inputs:

image-work/
  originals/
  converted/
  failed-review/
  reports/

Do not move the original automatically unless the team expects that behavior. Instead, copy or list failed paths in a report. A reviewer can then inspect the files, replace bad downloads, export unsupported design assets, or mark intentional exclusions.

This approach is especially useful when an AI agent is helping. The agent can prepare a concise list of failed paths and likely causes. It should not invent a replacement image or silently delete failed inputs.

For example, a useful failed-input note might look like this:

Input: ./assets/team/headshot-amy.jpg
CLI status: error
CLI error: Decode failed: Invalid JPEG marker
Review category: decode_failed
File size: 18 KB, expected roughly 300 KB from source export
Next action: re-export from design archive, then rerun this file only
Do not: delete the page reference or replace with an unrelated image

That record is short, but it prevents two common mistakes: treating a corrupt source as a successful exclusion, or letting an automation step update image references before the replacement exists.

Decide the Next Action#

Every failed input should end in one of a few outcomes:

• replace the corrupt source
• export a supported raster file
• exclude the asset from conversion
• fix permissions or output paths
• keep the original format
• retry after the upstream sync finishes

That list keeps troubleshooting practical. It also prevents the team from treating the converter as the place where every image problem must be solved.

Corrupt and unsupported inputs are normal in real asset folders. A mature workflow does not avoid them by luck. It identifies the failed path, verifies the actual file, separates unsupported formats from broken files, reports partial failures clearly, and leaves enough evidence for the next person to fix the source of the problem.