Cómo solucionar docker run con exit code 1 en Raspberry Pi

Explicación técnica

El error Exited (1) indica que el proceso principal del contenedor terminó con un código de salida no cero —es decir, falló. El hecho de que funcione en una VM de Raspberry Pi pero no en el hardware físico apunta a una diferencia en el entorno de ejecución. Las causas más comunes en Raspberry Pi son:

• Arquitectura incompatible: La imagen se construyó para amd64 (x86_64) y se intenta ejecutar en ARM (armv7l o aarch64).
• Falta de emulación QEMU: Sin binfmt_misc configurado, Docker no puede ejecutar binarios de otra arquitectura.
• Problemas de permisos o recursos: En hardware real, puede haber limitaciones de memoria, permisos de dispositivo o falta de drivers.
• Comandos inválidos en docker run: El espacio en --net = host (con espacios alrededor del =) es un error de sintaxis que no siempre es detectado por Docker, pero puede causar comportamientos erráticos.

Pasos para solucionar

1. Verifica la arquitectura del host y la imagen

# Arquitectura del Raspberry Pi (hardware físico)
uname -m

# Arquitectura de la imagen
docker inspect myimage --format '{{.Architecture}}'

Si uname -m muestra armv7l o aarch64, y la imagen reporta amd64, la arquitectura no coincide.

2. Corrige la sintaxis del comando docker run

El comando original tiene un error grave: --net = host (espacios alrededor del =). Docker interpreta = como parte del valor del flag, lo que puede causar fallos silenciosos o errores de parseo.

✅ Comando corregido:

docker run --net=host -d -t myimage

⚠️ Nota crítica: En versiones recientes de Docker, --net=host no funciona en contenedores no Linux (como en Raspberry Pi con armhf), y puede causar fallos si el kernel no lo soporta. Si el contenedor no necesita acceso directo a la red del host, usa --net=bridge.

3. Ejecuta en primer plano para ver el error real

docker run --net=host -it --rm myimage

Elimina -d (background) y añade -it para ver logs en tiempo real y capturar errores.

4. Si la arquitectura es incompatible, usa QEMU

Instala soporte multiarquitectura:

# Instala binfmt-support y QEMU
sudo apt update && sudo apt install -y qemu-user-static binfmt-support

# Registra los binarios QEMU para Docker
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Luego ejecuta de nuevo tu contenedor.

5. Verifica logs del contenedor

docker ps -a  # Encuentra el ID del contenedor con Exited (1)
docker logs <container_id>

Bloque de código corregido (ejemplo funcional)

# Paso 1: Verifica arquitectura
uname -m
docker inspect myimage --format '{{.Architecture}}'

# Paso 2: Corrige sintaxis y ejecuta en primer plano
docker run --net=host -it --rm myimage

# Paso 3 (si falla por arquitectura): Instala QEMU
sudo apt update && sudo apt install -y qemu-user-static binfmt-support
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# Paso 4: Reintenta
docker run --net=host -d -t myimage

Pro-tip: Construye imágenes nativas para ARM

Si controlas la construcción de la imagen, nunca uses imágenes amd64 en Raspberry Pi. Usa:

# En el Dockerfile, especifica plataforma explícitamente
FROM --platform=linux/arm/v7 raspbian/stretch

# O para Raspberry Pi 4 (64-bit)
FROM --platform=linux/arm64 ubuntu:22.04

Y construye con:

docker build --platform linux/arm/v7 -t myimage .

✅ Consejo definitivo: Usa docker buildx para construir multiarquitectura:

docker buildx build --platform linux/arm/v7,linux/arm64 -t myimage .

Esto evita 99% de los errores de Exited (1) en Raspberry Pi.

🚀 ¿Quieres más soluciones técnicas?

Si te sirvió esta ayuda, suscríbete para recibir los errores más comunes de la semana y cómo evitarlos.
👉 Suscríbete aquí