セルフホスト型ギャラリーでHEIC写真のプレビューが表示されなくなる原因は？

エヴァ・ウォン

IceWhale author

エヴァ・ウォン は テクニカルライター であり ZimaSpaceの常駐ティンカーでもあります。 生涯のオタクであり、 ホームラボとオープンソースソフトウェアに情熱を持っています。彼女は複雑な技術的概念をわかりやすく、 実践的なガイドに翻訳することを専門としています。エヴァはセルフホスティングは楽しくあるべきで、怖がるものではないと信じています。彼女のチュートリアルを通じて、コミュニティが ハードウェアのセットアップを解明する手助けをしています。初めてのNAS構築からDockerコンテナの習得まで。

What Causes HEIC Photos to Lose Previews in a Self-Hosted Gallery?

HEICのプレビューが表示されなくなるのは、ギャラリーが元ファイルをデコードできない、派生画像を生成できない、またはその派生画像を現在のクライアントに配信できない場合です。

セルフホスト型のギャラリーでは通常、HEICのオリジナルを保持したまま、すべてのHEIFプロファイルを直接表示できない可能性があるブラウザーやスマートフォン向けに、JPEGまたはWebPのサムネイルとプレビューを作成します。破損、新しいスマートフォンのエンコードプロファイル、非常に大きな画像サイズ、デコーダーのサポート不足、ワーカージョブの失敗、古いサムネイル記録、クライアント側でのオリジナル読み込みなどが派生画像の処理経路にのみ影響する場合、タイムラインが空白でもオリジナルはダウンロードできます。1つのファイルについて、オリジナルのバイトデータから生成済みプレビューまでを確認してください。

オリジナルのHEICファイルが正常か確認する

ギャラリーからオリジナルをダウンロードし、元のスマートフォン、エクスポートファイル、またはバックアップとサイズおよびハッシュを比較します。HEICに対応した信頼できるデスクトップアプリケーションで開いてください。

Immichでは、HEICやDNGをアップロードした後にサムネイルとプレビューの生成が停止したという報告があります。そのため、破損したオリジナルと派生画像パイプラインの失敗を切り分けることが重要です。確認された症状は、アップロード後にサムネイルが表示されないというものでした。

ダウンロードしたオリジナルが途中で切れている、または破損している場合は、転送経路を修正し、検証済みのソースから再アップロードします。オリジナルが正常に開く場合は、それを保持したまま、メタデータ、デコーダー、ジョブレベルの確認を続けてください。

正常なHEICと失敗するHEICのメタデータを比較する

プレビューが生成されるHEICファイルと、生成されないHEICファイルを1つずつ選びます。デバイスモデル、オペレーティングシステムのバージョン、画像サイズ、ビット深度、カラープロファイル、補助画像、向き、HDRメタデータ、ファイルサイズ、コンテナブランドを比較してください。

新しいスマートフォンのソフトウェアによって、現在のサーバーデコーダーが認識できないプロファイルが導入されることがあります。Immichのある issue では、iOS 18のHEICファイルで不正なヘッダーに関するメッセージとともにサムネイル生成に失敗し、それ以前のiOS画像は正常に動作しました。このことから、新しいソースプロファイルの違いを特定できます。

原因を分類するため、カメラ設定を1つだけ変更した後、同じスマートフォンで別の写真を試します。互換性のないプロファイルとサーバーバージョンが判明するまでは、オリジナルのライブラリを変換したり上書きしたりしないでください。

画像サイズとリソース制限を確認する

問題の画像の幅、高さ、メガピクセル数、ファイルサイズ、埋め込まれた補助画像を記録します。非常に大きなHEICファイルは、圧縮後のファイルサイズから想像するよりも、デコード時にはるかに多くのメモリを必要とする場合があります。

Immichでは、200メガピクセルの大きなHEICファイルでサムネイルを生成できず、プレビューも表示できない事例が報告されています。実際の境界は通常のギャラリー閲覧ではなく、極端に大きなHEIC画像サイズでした。

1つのファイルを処理している間、サムネイルワーカーのメモリ、CPU、コンテナ制限、メモリ不足イベントを監視します。小さなHEIC画像が正常に動作する場合は、ワーカーに割り当てるリソースを増やすか、フル解像度のオリジナルを破棄せず、互換性のあるプレビュー用コピーを保持してください。

Featured

ZimaCube 2 パーソナルクラウドホームNAS

ZimaCube2

サムネイルワーカーで最初に発生したデコードエラーを確認する

影響を受けたファイルを1つ選び、サムネイルの欠落または再生成ジョブを実行して、マイクロサービスまたはワーカーのログを追跡します。最終的な一般エラーではなく、最初に発生したデコーダー、ヘッダー、色空間、権限、または書き込みエラーを記録してください。

最近のImmichの報告でも、アップグレード後に特定のHEICファイルでサムネイル生成に失敗する事例が続いています。2026年のある issue では、アップグレードに関連したHEIC処理の失敗が確認されています。

最初のHEICエラーの後、新しいファイルがすべて失敗する場合は、ログを保存してキューの状態を確認したうえで、失敗したワーカーだけを再起動します。1つの不正なファイルによって、ワーカープロセス自体が停止し、その後のプレビューをすべて生成できなくなったかどうかが分からなくならないようにしてください。

デコーダーライブラリとバージョンの互換性を確認する

ギャラリーのバージョン、コンテナイメージ、画像処理ライブラリ、HEIFデコーダー、CPUアーキテクチャ、アップデート時にハードウェア固有のビルドが変更されたかどうかを記録します。最後に正常だったデプロイと比較してください。

HEICの問題は、同じサーバーバージョン内でも一部の画像だけに影響する場合があります。Immichの issue では、特定のHEICファイルだけで失敗したことが報告されており、HEICサポートが完全に存在しないのではなく、フォーマット機能の境界であることを示しています。

同じオリジナルを、以前のアプリケーションバージョンまたは分離した現在のワーカーイメージでテストします。データベースと設定の一貫したバックアップがある場合に限ってロールバックしてください。画像デコーダーを試すために、本番データベースを確認せずにダウングレードしてはいけません。

サーバー側のプレビュー失敗とクライアント側のオリジナル読み込みを切り分ける

問題のファイルをWebクライアント、モバイルアプリ、プライベートブラウザーセッションで開きます。タイムラインのサムネイル、中サイズのプレビュー、フルサイズの派生画像、オリジナルのダウンロードが、それぞれ個別に失敗するかを記録してください。

ブラウザーがオリジナルのHEICを表示できない場合でも、生成済みのプレビューは表示できることがあります。ImmichのSafariに関する issue では、クライアントがプレビューまたはフルサイズの派生画像にフォールバックできる一方で、オリジナルのHEIC読み込みに失敗することが説明されています。

1つのクライアントだけで失敗する場合は、そのクライアントにキャッシュされたアセットのレスポンスを消去し、オリジナル読み込みの設定を比較します。すべてのクライアントでサムネイルが表示されず、ワーカーログにも生成済みファイルがない場合は、サーバー側の問題として調査を続けてください。