DEV Community

Erick Eduardo Ramos
Erick Eduardo Ramos

Posted on

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

#debugging #devops #docker #raspberrypi

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

¿Por qué ocurre este error?

El código de salida 1 indica que el proceso principal del contenedor terminó con un error genérico. En Raspberry Pi, los casos más comunes son:

  • Arquitectura incompatible: La imagen se construyó para amd64 (x86_64) pero Raspberry Pi usa arm32v7 o arm64v8.
  • Falta de binarios compatibles: El ENTRYPOINT o CMD del contenedor no existe o no es ejecutable en ARM.
  • Problemas de permisos o dependencias faltantes: Librerías del sistema (como libc, libstdc++, etc.) no están disponibles en la versión del sistema operativo de la Pi.
  • Uso de --net=host mal formateado: El espacio después del = (--net = host) es inválido y puede causar fallos silenciosos.

🔍 Nota crítica: El error se presenta solo en la Raspberry Pi física, pero funciona en una VM. Esto apunta fuertemente a incompatibilidad de arquitectura.

Pasos para solucionarlo

1. Verifica la arquitectura de tu Raspberry Pi 

uname -m
# Salida esperada: armv7l (Raspberry Pi 3/4 32-bit) o aarch64 (Raspberry Pi 4/5 64-bit)
Enter fullscreen mode Exit fullscreen mode

2. Verifica la arquitectura de tu imagen 

docker inspect myimage --format '{{.Architecture}}'
# Si muestra "amd64", es incompatible con Raspberry Pi
Enter fullscreen mode Exit fullscreen mode

3. Corrige el comando docker run

El error de sintaxis es crítico:

# ❌ INCORRECTO (espacios alrededor del '=')
docker run --net = host -d -t myimage

# ✅ CORRECTO (sin espacios)
docker run --net host -d -t myimage
Enter fullscreen mode Exit fullscreen mode

⚠️ --net = host hace que Docker interprete = como parte del valor del flag --net, lo que genera un error silencioso y el contenedor falla al iniciar.

4. Ejecuta en primer plano para diagnosticar 

docker run --net host -it --rm myimage
Enter fullscreen mode Exit fullscreen mode
  • Elimina -d (background) y -t (TTY), añade -it para ver logs en tiempo real.
  • Si falla, verás el mensaje de error directamente (ej: exec format error, No such file or directory, etc.).

5. Solución definitiva: reconstruye la imagen para ARM

Opción A: Usa imágenes oficiales con soporte multi-arch 

docker pull arm32v7/alpine:latest  # Para Pi 3/4 32-bit
docker pull arm64v8/alpine:latest  # Para Pi 4/5 64-bit
Enter fullscreen mode Exit fullscreen mode

Opción B: Construye tu imagen con docker buildx 

# Habilita buildx
docker buildx create --use

# Construye para ARM
docker buildx build \
  --platform linux/arm/v7,linux/arm64 \
  -t myimage:latest \
  --push \
  .
Enter fullscreen mode Exit fullscreen mode

Opción C: Usa QEMU para emulación (solo para depuración) 

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
docker run --platform linux/arm/v7 myimage
Enter fullscreen mode Exit fullscreen mode

❗ No recomendado para producción: es lento y puede fallar por falta de drivers específicos.

Bloque de código corregido (ejemplo funcional) 

# Paso 1: Verifica arquitectura
uname -m

# Paso 2: Corrige el comando (¡sin espacios!)
docker run --net host -d -t myimage

# Paso 3: Si sigue fallando, ejecuta en primer plano
docker run --net host -it --rm myimage

# Paso 4: Si el error es "exec format error", reconstruye para ARM
docker buildx build --platform linux/arm/v7 -t myimage-arm:latest .
Enter fullscreen mode Exit fullscreen mode

Pro-tip: Diagnóstico rápido con docker logs

Si ya tienes el contenedor en estado Exited (1):

# Recupera logs del último contenedor
docker logs $(docker ps -lq)

# O inspecciona el código de salida explícitamente
docker inspect $(docker ps -lq) --format '{{.State.ExitCode}}'
Enter fullscreen mode Exit fullscreen mode

📌 Consejo final: En Raspberry Pi, nunca uses imágenes amd64 nativas. Usa siempre imágenes con etiquetas arm32v7, arm64v8 o construidas con buildx. El error Exited (1) en Pi es casi siempre un problema de arquitectura o sintaxis en el comando.

Top comments (0)