What Causes HEIC Photos to Lose Previews in a Self-Hosted Gallery?
HEIC previews disappear when the gallery cannot decode the original, generate its derivative image, or deliver that derivative to the current client.
A self-hosted gallery normally preserves the HEIC original while creating JPEG or WebP thumbnails and previews for browsers and phones that may not display every HEIF profile directly. The original can remain downloadable even when the timeline is blank because corruption, a new phone encoding profile, very large dimensions, missing decoder support, failed worker jobs, stale thumbnail records, or client-side original loading affects only the derivative path. Diagnose one asset from original bytes through generated preview.
Confirm Whether the Original HEIC File Is Intact
Download the original from the gallery and compare its size and hash with the source phone, export, or backup. Open it in a trusted desktop application that supports HEIC.
Immich users have reported HEIC and DNG uploads after which thumbnails and previews stopped generating, making it important to separate a damaged original from a failed derivative pipeline. The visible symptom was missing thumbnails after upload.
If the downloaded original is truncated or corrupt, repair the transfer path and re-upload from a verified source. If the original opens correctly, preserve it and continue with metadata, decoder, and job-level checks.
Compare Working and Failing HEIC Metadata
Choose one HEIC file that generates previews and one that does not. Compare device model, operating-system version, dimensions, bit depth, color profile, auxiliary images, orientation, HDR metadata, file size, and container brands.
New phone software can introduce a profile that the current server decoder does not understand. An Immich issue found iOS 18 HEIC files failing thumbnail generation with incorrect-header messages while older iOS images still worked, isolating a new source-profile difference.
Test another photo from the same phone after a camera-setting change only to classify the failure. Do not convert or overwrite the original library until the incompatible profile and server version are known.
Check Image Dimensions and Resource Limits
Record the failing image’s width, height, megapixels, file size, and embedded auxiliary images. Very large HEIC files can require substantially more memory during decode than their compressed file size suggests.
Immich has documented large 200-megapixel HEIC files that could not produce thumbnails or display previews. The practical boundary was extremely large HEIC dimensions, not ordinary gallery browsing.
Monitor the thumbnail worker’s memory, CPU, container limits, and out-of-memory events while processing one file. If smaller HEIC images work, increase the supported worker resources or keep a compatible preview copy without discarding the full-resolution original.
Read the Thumbnail Worker’s First Decode Error
Run the missing-thumbnail or regeneration job for one affected asset and follow the microservice or worker log. Capture the first decoder, header, colorspace, permission, or write error rather than the final generic failure.
Recent Immich reports continue to show thumbnail generation failing for specific HEIC files after upgrades. One 2026 issue identifies an upgrade-associated HEIC processing failure.
If every new file fails after the first HEIC error, restart only the failed worker after preserving logs and verify queue health. A single malformed asset should not be allowed to obscure whether the worker process itself stopped generating all later previews.
Verify Decoder Libraries and Version Compatibility
Record the gallery version, container image, image-processing library, HEIF decoder, CPU architecture, and whether hardware-specific builds changed during the update. Compare them with the last known-good deployment.
Some HEIC failures affect only a subset of images even within one server version. An Immich issue reports that only certain HEIC files failed, indicating a format-feature boundary rather than a complete absence of HEIC support.
Test the same original with the previous application version or an isolated current worker image. Roll back only from a consistent database and configuration backup; do not downgrade the production database blindly to test an image decoder.
Separate Server Preview Failure From Client Original Loading
Open the affected asset in the web client, mobile app, and a private browser session. Record whether the timeline thumbnail, medium preview, full-size derivative, and original download fail independently.
A browser may fail to display the original HEIC while a generated preview should still work. An Immich Safari issue describes original HEIC loading failing even though the client could fall back to a preview or full-size derivative.
If only one client fails, clear that client’s cached asset response and compare original-loading settings. If all clients lack the thumbnail and the worker log shows no generated file, keep the diagnosis on the server side.
Regenerate Only Missing Derivatives After the Cause Is Fixed
Back up the database and metadata volume, then run the application’s missing-thumbnail job on a small affected set. Confirm that it creates new derivatives without replacing originals.
Immich releases have directed users with broken thumbnails to run the missing-thumbnail job after relevant fixes, which supports targeted regeneration after repair rather than deleting the complete thumbnail store first.
The ZimaSpace guide to private iPhone photo backup provides the surrounding requirement: preserve and verify original photos independently from gallery previews.
The issue is resolved when the original hash remains unchanged, the worker generates thumbnails for the failing HEIC profile, all supported clients load the derivative, and a new photo from the same phone processes correctly without a full-library rebuild.
Recommended products
Support & Tips
More to Read
Why Does a Docker Volume Restore Recreate File Contents but Drop Extended Attributes?
A volume-restore diagnosis covering xattr inventory, tar and Rsync options, namespaces, destination support, privileges, labels, app metadata, and tests.
Why Does a Running Container Keep Its Old Memory Limit After the Compose File Changes?
A memory-limit diagnosis covering live cgroups, restart versus recreation, Compose fields, hard and soft limits, parent scopes, swap, and runtime heaps.
Why Does Restarting a Reverse Proxy Invalidate Every Session for One Self-Hosted App?
A session-loss diagnosis covering restart scope, cookie ownership, secret rotation, cache-backed sessions, sticky routing, auth gateways, and recovery.
