RAW and HEIC Preview Troubleshooting Guide for Photo Servers

Trace one failing RAW or HEIC asset from original bytes to decoder, worker, derivative file, and client before regenerating anything in bulk.

When originals download but previews fail, the cause may be a camera-specific encoding, a decoder mismatch, a stalled job, an unwritable thumbnail path, or a client requesting a different asset. Pair one failing sample with one known-good file, change one layer at a time, and preserve both originals. A full-library rebuild is justified only after the same canary survives worker restart and loads through every client path in scope.

Choose one failing asset and prove the original

Select one failing RAW or HEIC file and one working file from the same camera or phone. Record extension, codec profile, dimensions, bit depth, size, capture device, application version, and client. Download the original and compare its hash and byte size with the source or backup.

A solved community report of HEIC error loading image case shows that an “error loading image” can persist even after repeatedly starting thumbnail jobs. Use that symptom only to justify tracing the pipeline; it does not prove the file, decoder, or queue is the universal cause.

Open both originals with an independent decoder. If the failing original is corrupt or truncated, restore it before touching previews. If both originals decode, preserve them read-only and proceed; a derivative problem should never trigger conversion or deletion of the only source file.

Separate decoder support from job execution

Run the same decoder or metadata extraction stack used by the application against both samples, capturing stderr and exit status. A fail on one camera profile, compression mode, or HEIC variant points to scoped format support; success for both means the error occurs after decoding.

Use the ZimaSpace branch for decoder failure or thumbnail worker error when the RAW sample fails before queue work. It keeps camera-specific decoding separate from a worker that never claims the job or cannot write output.

Upgrade or change a decoder only in a test container and re-run the exact sample. If the original decodes after the change, generate one preview and confirm color, orientation, and dimensions; if it still fails, roll back and retain the sample and command output for platform support.

Trace the worker, queue, and derivative path

Enqueue only the canary and note job ID, worker assignment, start and finish time, retry count, error, output path, owner, free space, and inode availability. Check that host and container paths refer to the same writable location and that no backup or cleanup task is locking it.

An independent missing originals and failed thumbnails separates missing originals from thumbnail jobs, storage mounts, permissions, and client routes. Use those path-level distinctions, but match the fix to the first failing observation in your own logs.

Clear or retry only the canary job. A pass produces a derivative at the expected path and leaves the queue healthy; a fail with decoder success narrows the cause to worker identity, queue state, memory, output storage, or database status. Do not purge every thumbnail record to make one job move.

-15% OFF

ZimaBoard 2 - Mini Home Server for Your Big Idea

Single board computer zimaboard2

$339.00 - $519.00

Buy Now

Compare clients and validate before bulk regeneration

Load the canary on web, iOS, Android, and any reverse-proxied path in scope. Record whether each requests a thumbnail, preview, or original and compare response code and content type. One client failure with a healthy stored derivative belongs to delivery or client compatibility, not the source decoder.

Apply one matched fix, restart the affected worker once, and test the same failing file plus a new file from the same camera. Then sample other formats to ensure the change did not break JPEG, video, HDR, or color handling.

Start bulk regeneration only when the canary survives restart, storage has headroom, and backups are outside the job window. Stop if originals change, errors spread to working formats, or queue retries accelerate; escalate with the sample, decoder output, job ID, and client response intact.