テクノロジー · 実用ガイド

Docker pull の manifest unknown？削除前に remote reference を証明する

展開済み registry、repository、tag または digest を保存し、remote descriptor と認証 view を確認します。

執筆 Watch at Ease News · 4 分で読めます公開 2026/10/16 11:20 UTC

manifest unknown は local cache の一般エラーではなく、registry が name/tag を見つけられない応答です。

reference、descriptor、platform、runtime を分けて確認します。

展開済み reference を保存

完全なエラーと、実際に実行されたコマンド、Compose サービス、またはデプロイ項目を保存します。registry、namespace、repository、tag または digest を記録し、変更前に CI 変数を出力します。

最初に image を prune したり builder cache を消したりしないでください。MANIFEST_UNKNOWN は要求したリモート名と tag に対する registry の応答であり、ローカル layer を削除してもリモート manifest は作られません。

reference を registry、repository path、image name、tag の四つに分けます。tag を省略すると通常 latest が要求されますが、repository が存在しても latest が公開されているとは限りません。

大文字小文字、区切り文字、CI の展開結果を一文字ずつ比較します。login や別 tag の成功は一部の内容へのアクセスを示すだけで、この reference の存在は証明しません。

registry UI または認証済みの manifest inspection コマンドで正確な tag を調べ、返された digest と media type を記録します。tag がなければ、実在する不変 tag を選ぶか publisher を修正します。

digest が固定されている場合は、その digest を直接照会します。tag は移動できますが digest は内容で決まるため、別々に検査し、失敗した reference を記録に残します。

tag が image index に解決される場合、必要な OS と architecture の descriptor を確認します。tag は存在するが platform がない状態は、name/tag の MANIFEST_UNKNOWN とは別の分岐です。

amd64 が成功したから arm64 や Windows も存在すると仮定しないでください。workload に合う場合だけ、variant の公開、対応 tag の選択、または target platform の変更を行います。

対話環境では成功し CI だけ失敗する場合、展開済み文字列、資格情報、registry hostname、proxy、network path を比較します。mirror や pull-through cache は origin と異なる view を持つことがあります。

最後に、失敗したものと同じ runtime と registry path から正確な tag または digest が解決できることを証明します。descriptor digest と platform を記録し、再現性が必要なら不変 reference を固定します。