Tecnología · GUÍA PRÁCTICA
¿Docker pull dice manifest unknown? Prueba la referencia remota antes de limpiar
Conserva registry, repositorio, tag o digest ya expandidos; demuestra el descriptor y la vista autenticada antes de podar o cambiar plataforma.
manifest unknown no es un fallo genérico de caché local: es la respuesta del registro para nombre y tag.
Separa referencia, descriptor, plataforma y runtime antes de corregir.
Conserva la referencia expandida
Copia el error completo y el comando, servicio de Compose o campo de despliegue que lo produjo. Anota el host del registro, el namespace, el repositorio, el tag o el digest, e imprime las variables de CI antes de cambiarlas.
No empieces podando imágenes ni borrando la caché del builder. MANIFEST_UNKNOWN es una respuesta del registro sobre el nombre y tag remotos solicitados; eliminar capas locales no puede crear ese manifest remoto.
Resuelve los valores implícitos
Divide la referencia en registro, ruta del repositorio, nombre de imagen y tag. Si no se escribe un tag, Docker suele pedir latest; un repositorio puede existir sin publicar ese tag.
Compara cada carácter, incluidas mayúsculas, separadores y sustituciones de CI. Un login correcto o la existencia de otro tag demuestran acceso a parte del registro, no que esta referencia exacta exista.
Consulta tag y descriptor
Consulta el tag exacto con la interfaz del registro o un comando autenticado de inspección de manifests. Anota el digest y el media type devueltos. Si falta el tag, elige uno inmutable existente o corrige el publicador.
Si ya hay un digest fijado, consulta ese digest directamente. Un tag puede moverse mientras un digest depende del contenido, así que pruébalos por separado y conserva la referencia fallida en el incidente.
Separa tag de plataforma
Cuando el tag resuelva a un image index, revisa sus descriptores para el OS y la arquitectura necesarios. Un tag presente sin la plataforma correcta es una rama distinta del MANIFEST_UNKNOWN para nombre y tag.
No supongas que existen variantes arm64, amd64 o Windows porque otra plataforma funciona. Publica la variante, selecciona un tag compatible o cambia la plataforma objetivo solo si coincide con la carga de trabajo.
Compara CI, mirror y registro
Si funciona de forma interactiva pero falla en CI, compara la cadena expandida, las credenciales, el hostname del registro, el proxy y la ruta de red. Un mirror o pull-through cache puede mostrar una vista distinta del origen.
Termina con una prueba: el tag o digest exacto resuelve desde el mismo runtime y ruta de registro que fallaron. Registra el digest del descriptor y la plataforma, y fija una referencia inmutable cuando importe la reproducibilidad.
