DEV Community

Erick Eduardo Ramos
Erick Eduardo Ramos

Posted on

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

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, este problema es muy frecuente cuando se ejecutan contenedores construidos para arquitecturas x86/x64 (como amd64) sobre una CPU ARM (como la de Raspberry Pi: armv7l o aarch64). Docker no da un error explícito de arquitectura incompatible —simplemente ejecuta el binario, este falla al inicio y el contenedor sale con código 1.

Otras causas comunes en Raspberry Pi:

  • Falta de permisos para acceder a dispositivos (GPIO, cámara, etc.)
  • Variables de entorno faltantes (DISPLAY, LD_LIBRARY_PATH, etc.)
  • Binarios no compatibles con la versión del kernel (ej. musl vs glibc)
  • Uso de --net=host con permisos insuficientes en sistemas con cgroup v2 (Raspberry Pi OS Bullseye+)

Pasos para diagnosticar y solucionar

1. Ejecuta el contenedor en primer plano (sin -d) 

docker run --net=host -it --rm myimage
Enter fullscreen mode Exit fullscreen mode

⚠️ Nota: Quita los espacios en --net=host (tu comando original tiene --net = host, lo cual es inválido y causante de fallos silenciosos).

2. Verifica la arquitectura del contenedor vs. la del host 

# En el host (Raspberry Pi):
uname -m

# En el contenedor (si puedes ejecutarlo temporalmente):
docker run --rm -it --platform linux/arm/v7 alpine uname -m
Enter fullscreen mode Exit fullscreen mode

3. Construye o descarga la imagen con arquitectura correcta

Si usas docker build, asegúrate de especificar la plataforma:

docker build --platform linux/arm/v7 -t myimage .
Enter fullscreen mode Exit fullscreen mode

O si usas imágenes de Docker Hub:

docker pull arm32v7/myimage  # o
docker pull arm64v8/myimage
Enter fullscreen mode Exit fullscreen mode

4. Usa --privileged solo como último recurso (no recomendado para producción) 

docker run --net=host --privileged -d -t myimage
Enter fullscreen mode Exit fullscreen mode

🔒 Esto deshabilita todas las restricciones de seguridad. Solo úsalo si el contenedor necesita acceso directo a hardware (ej. GPIO).

Bloque de código corregido (caso más común: arquitectura) 

# Paso 1: Verifica arquitectura del host
uname -m  # Ej: armv7l o aarch64

# Paso 2: Construye con plataforma correcta (ajusta según tu caso)
docker build --platform linux/arm/v7 -t myimage .

# Paso 3: Ejecuta sin errores de red
docker run --net=host -d -t myimage
Enter fullscreen mode Exit fullscreen mode

✅ Verificación final: Ejecuta docker logs <container_id> tras el fallo para confirmar el mensaje de error específico (ej. exec format error).

Pro-tip: Diagnóstico rápido con strace

Si el error persiste y no puedes ver el log:

docker run --net=host --rm -it \
  --cap-add=SYS_PTRACE \
  --security-opt seccomp=unconfined \
  myimage strace -f -o /tmp/strace.log /bin/sh
Enter fullscreen mode Exit fullscreen mode

Luego revisa /tmp/strace.log para identificar dónde falla el proceso.

¿Por qué funciona en la VM pero no en hardware real?

  • Las VMs de Raspberry Pi suelen emular x86 (ej. con QEMU) o correr imágenes amd64 con compatibilidad.
  • El hardware real no puede ejecutar binarios x86 sin emulación lenta y problemática.
  • Docker no emula automáticamente: si la imagen no tiene el manifest ARM, fallará.

💡 Solución definitiva: Usa imágenes oficiales con soporte multi-arch (arm32v7, arm64v8) o construye tu propia imagen con --platform.

Top comments (0)