Tecnología · GUÍA PRÁCTICA
Docker muestra exec format error: revise imagen, binario y entrada antes de reconstruir
Un exec format error no se diagnostica solo por la etiqueta. Revise el manifiesto seleccionado, los archivos finales, la arquitectura del ejecutable y su intérprete antes de borrar cachés, añadir QEMU o reconstruir a ciegas.
En contenedores Linux, «exec format error» significa que el kernel no pudo ejecutar el archivo recibido. La arquitectura de CPU es una posible causa; también puede fallar un script sin una cabecera de intérprete utilizable u otro formato ejecutable inválido. Primero identifique el archivo exacto y la etapa que falló; después elija la reparación.
Conserve la imagen fallida y la salida del error. Un registro útil conecta cuatro elementos: el host de ejecución, el manifiesto seleccionado, el ejecutable real del sistema de archivos final y el comando que intentó iniciarlo. Una etiqueta de arquitectura coincidente demuestra menos que comprobar los cuatro.
1. Registrar la ejecución fallida antes de reconstruir
Guarde el error completo, la referencia y el digest de imagen, el ID del contenedor si existe, la plataforma solicitada y el Docker context utilizado. Inspeccione la configuración y los montajes del contenedor fallido, no solo el Dockerfile: las anulaciones del punto de entrada o los scripts montados pueden cambiar el archivo ejecutado. Use docker container inspect CONTAINER para la configuración y docker image inspect IMAGE para los metadatos locales.
El host relevante es el daemon de Docker o el trabajador de compilación que ejecuta el proceso; puede ser remoto o estar en la VM Linux de Docker Desktop. El procesador del portátil no basta para identificarlo. Distinga también el fallo de una instrucción RUN del fallo al iniciar el contenedor terminado. Si RUN menciona /bin/sh, examine el entorno de esa etapa; si falla la entrada de la aplicación, examine el sistema de archivos de ejecución final.
2. Comparar la variante del registro con la imagen local
Use docker buildx imagetools inspect IMAGE_REFERENCE para examinar los manifiestos y variantes de plataforma de la referencia del registro. Compárelos con la imagen local exacta y la plataforma solicitada en el intento fallido. Una etiqueta mutable puede apuntar a otra imagen después del fallo: conserve el digest original y no trate la etiqueta actual como prueba del pasado.
Si falta la variante necesaria, seleccione o construya la correcta. Si existe pero se eligió otra, investigue la plataforma explícita y la configuración del despliegue. --platform=linux/amd64 selecciona un destino; no convierte archivos arm64 arbitrarios ya copiados. La falta de un manifiesto compatible puede causar un error de selección antes de ejecutar, en una etapa distinta de ENOEXEC.
3. Inspeccionar el archivo sin iniciar el comando que falla
Si existe un contenedor fallido detenido, docker cp CONTAINER:/path/to/file ./artifact-to-inspect permite copiar el archivo sospechoso. Docker documenta la copia desde contenedores detenidos. Si solo existe la imagen, docker create IMAGE crea un contenedor sin iniciarlo; anote el ID devuelto e inspecciónelo. Revise los montajes por separado porque los archivos aportados durante la ejecución pueden diferir de la imagen.
Utilice una herramienta de inspección fiable, como file, sobre el archivo copiado. Para un binario ELF, readelf -h muestra el tipo de máquina y readelf -l puede revelar el intérprete de programa solicitado. Inspeccione el archivo; no lo ejecute para averiguar su arquitectura. Si faltan estas herramientas, use su entorno de análisis de confianza. No suponga que una imagen mínima o distroless contiene shell, file o readelf.
4. Rastrear los binarios copiados por las etapas
Enumere todas las etapas que crean o descargan ejecutables copiados a la imagen final. BUILDPLATFORM describe al trabajador de BuildKit y TARGETPLATFORM la salida solicitada. Una etapa fijada a la plataforma del constructor puede ejecutar compiladores nativos de forma intencionada, pero su configuración debe producir el artefacto de destino.
Los argumentos de destino predefinidos de Docker están disponibles globalmente, pero deben declararse con ARG para usarlos dentro de una etapa. Compruebe TARGETOS, TARGETARCH y, cuando corresponda, TARGETVARIANT; después compruebe la salida real de la cadena de herramientas. Declararlos no obliga a todos los compiladores a compilar de forma cruzada. Cambiar el FROM final a una base compatible tampoco transforma un ejecutable incompatible copiado desde otra etapa.
5. Separar scripts, intérpretes ausentes y permisos
En un script ejecutado directamente, examine los primeros bytes y la línea del intérprete: la cabecera #! debe señalar al intérprete previsto, que debe existir en el sistema de archivos de ejecución. Revise bytes inesperados antes de la cabecera y finales de línea de Windows. Invocar un shell explícito cambia cómo se lanza el script; no demuestra que se haya reparado la ejecución directa original.
Conserve la categoría exacta. Linux documenta ENOEXEC para formatos no reconocidos o arquitectura incorrecta; ENOENT si falta una ruta o un intérprete de script o ELF; y EACCES para denegaciones de permiso, como falta de ejecución o un montaje noexec. Un archivo visible puede fallar porque falta su intérprete. chmod no repara una arquitectura de CPU equivocada, y añadir emulación no instala un intérprete ausente.
6. Cambiar una causa y demostrar que funciona la ruta original
Elija la rama respaldada por pruebas: variante ausente, corregir selección o salida de compilación; binario interno equivocado, reconstruir o sustituir ese artefacto; script mal formado, reparar cabecera o codificación; intérprete ausente, aportar el entorno compatible; permiso denegado, revisar usuario, modo y política de montaje. Borrar imágenes no sustituye la identificación de la rama.
La emulación es una alternativa deliberada para ejecutar código no nativo. Verifique el soporte del trabajador real antes de cambiar el registro binfmt de todo el host; Docker Desktop y BuildKit oficial pueden proporcionarlo ya. Tras reparar, pruebe el mismo comando previsto, plataforma, usuario y montajes relevantes en un entorno desechable fuera de producción. Registre el nuevo digest y la comprobación concreta que cambió. Si aún falla, conserve el nuevo error y continúe desde esa capa en lugar de repetir la misma reconstrucción.
