科技 · 實用指南

Docker pull 顯示 manifest unknown？清理前先證明遠端 reference

保存展開後的 registry、repository、tag 或 digest；先證明遠端 descriptor 與驗證視圖。

作者 Watch at Ease News · 3 分鐘閱讀發布於 2026年10月16日上午11:20 UTC

manifest unknown 是 registry 對請求 name 與 tag 的結果，不是泛化的 local cache error。

依 reference、descriptor、platform、runtime 分支核驗。

保存展開後的 image reference

複製完整錯誤與實際執行的命令、Compose 服務或部署欄位。記錄 registry 主機、命名空間、repository、tag 或 digest，並在更動前輸出 CI 變數。

不要先刪除映像或清理 builder cache。MANIFEST_UNKNOWN 是 registry 對遠端名稱與 tag 的回應；刪除本機 layer 不會建立遠端 manifest。

把 reference 拆成 registry、repository 路徑、image 名稱與 tag。若未寫 tag，Docker 通常會要求 latest，而 repository 可以存在但沒有發布 latest。

逐字比對大小寫、分隔符與 CI 展開值。成功登入或另一個 tag 可用，只能證明你能存取部分內容，不能證明這個 reference 存在。

使用 registry UI 或已驗證的 manifest inspection 命令查詢精確 tag，並記錄回傳的 digest 與 media type。tag 不存在時，選擇實際存在的不可變 tag，或修正發布流程。

若已固定 digest，就直接查詢該 digest。tag 可能移動，而 digest 依內容定址，因此要分開測試並保留失敗 reference。

tag 若解析為 image index，檢查其中是否有目標 OS 與 architecture 的 descriptor。tag 存在但缺平台，是不同於名稱或 tag 的 MANIFEST_UNKNOWN 分支。

不要因 amd64 可拉取就假設 arm64 或 Windows 版本存在。只有在符合 workload 時，才發布缺少的 variant、改用支援的 tag 或調整目標平台。

若互動環境成功而 CI 失敗，請比較展開後字串、憑證、registry hostname、proxy 與網路路徑。mirror 或 pull-through cache 可能與 origin 呈現不同內容。

以一項證據結案：從原本失敗的相同 runtime 與 registry 路徑解析精確 tag 或 digest，記錄 descriptor digest 與平台，並在需要可重現性時固定不可變 reference。