Solucionar docker run exit code 1 en Raspberry Pi
El error exit code 1 en Docker sobre Raspberry Pi es ese momento frustrante en que tirás tu docker run y el contenedor se muere antes siquiera de arrancar. No es un error de red ni de permisos de Docker en sí: es el proceso principal del contenedor fallando, y en la mayoría de los casos en Raspberry Pi la causa es que estás intentando correr una imagen compilada para arquitectura x86_64 sobre un procesador ARM. Te quedás mirando la terminal sin logs, sin pistas, y con un escueto exited (1) como única respuesta.
En 30 segundos
- El exit code 1 es un error genérico del proceso del contenedor que en Raspberry Pi casi siempre se debe a incompatibilidad de arquitectura: imágenes amd64 sobre ARM no corren sin ayuda.
- Verificá la sintaxis de tu comando. Un error común es poner espacios en
--net = host, que Docker interpreta como un nombre de red literal en vez de la opción correcta--net=host. - Usá
docker inspectpara revisar la plataforma de la imagen. Si diceamd64y tu Raspberry Pi es ARM, ahí está el problema (y necesitás QEMU o una imagen nativa ARM). - Ejecutá en primer plano con
-iten vez de-dpara ver los logs reales del error y no quedarte a ciegas.
El exit code 1 en Docker es un código de salida genérico que indica que el proceso principal del contenedor terminó con un error. En cualquier arquitectura puede aparecer por mil razones distintas, pero en Raspberry Pi el patrón es tan repetitivo que ya te lo puedo anticipar: frecuentemente es la arquitectura del binario, y otras veces es un error de tipeo en el comando que a todos nos pasó alguna vez.
¿Por qué aparece el error exit code 1 en Docker sobre Raspberry Pi?
El proceso principal del contenedor (ese que definiste con CMD o ENTRYPOINT) se ejecuta y falla. Docker te devuelve el código de salida de ese proceso, y el 1 es el comodín de “algo salió mal”. Ahora bien, en una Raspberry Pi los culpables más frecuentes son tres, según un análisis detallado:
- Arquitectura incompatible. Bajaste una imagen pensada para procesadores Intel/AMD (x86_64) y tu Raspberry Pi tiene un procesador ARM, ya sea arm32v7 (32-bit) en modelos más viejos o arm64v8 (64-bit) en los más nuevos.
- Falta de binarios compatibles. La imagen intenta ejecutar un binario compilado para otra arquitectura, y el kernel de Linux en la Raspberry Pi directamente no sabe qué hacer con eso. El error típico es
exec user process caused: no such file or directory. - Problemas de permisos o dependencias faltantes. En sistemas minimalistas como Raspberry Pi OS Lite, ciertas bibliotecas compartidas brillan por su ausencia —libc, libgl1, libasound2— y el proceso se va a pique apenas arranca.
Hay un cuarto caso, menos técnico pero igual de frecuente: errores de sintaxis en el comando docker run, en particular con la opción --net = host. Los espacios alrededor del igual confunden a Docker, que en vez de aplicar el modo host interpreta que querés conectar el contenedor a una red que se llama literalmente = o host como nombre, y el contenedor falla porque esa red no existe.
Corregí la sintaxis del comando docker run antes que nada
Parece una pavada, pero es una causa frecuente de exit code 1. Escribiste algo como docker run -d --name mi_contenedor --net = host mi_imagen y no entendés por qué no arranca. Lo que pasa es que Docker parsea = como un argumento posicional (nombre de red) y host como otro, en lugar de interpretar --net=host como la opción de red. Para más detalles técnicos, mirá en nuestra comparativa de CI/CD 2026.
La corrección es inmediata:
- ❌ Incorrecto:
docker run -d --net = host nginx(con espacios alrededor del igual, esto provocaexit code 1o directamente un error de red). - ✅ Correcto:
docker run -d --net=host nginx(sin espacios, Docker entiende que es el modo de red host).
Ojo con esto: --net=host no siempre funciona en Raspberry Pi OS si el sistema usa systemd-resolved para la resolución DNS. En esos casos el contenedor puede fallar al intentar acceder a interfaces de red que no están disponibles de la forma esperada. Si tu contenedor sigue fallando después de corregir la sintaxis, probá sin la opción --net=host directamente —muchas veces ni la necesitás.
Verificá la arquitectura de la imagen con docker inspect
Este es el paso que separa a los que resuelven el problema en cinco minutos de los que pierden una tarde entera. Corré esto en tu Raspberry Pi:
docker inspect --format '{{.Os}}/{{.Architecture}}' nombre_imagen
Si el output dice linux/amd64, ya sabés dónde está el problema. Los modelos de Raspberry Pi usan arquitecturas ARM: los modelos más viejos (Pi 3 y anteriores) son arm32v7, mientras que los Pi 4, Pi 5 y el Compute Module 4 son arm64v8 de 64 bits. Una imagen compilada para amd64 no puede ejecutarse nativamente en ARM sin ayuda de un emulador.
La solución directa es buscar una imagen oficial que tenga soporte multi-arquitectura. Docker Hub ya maneja esto bastante bien para imágenes populares: si hacés docker pull ubuntu:latest en una Raspberry Pi, el daemon de Docker negocia automáticamente la arquitectura y baja la variante ARM (si existe). Pero ojo, no todas las imágenes tienen builds para ARM, y muchas imágenes comunitarias están compiladas solo para amd64. Sobre eso hablamos en al elegir entre Jenkins y GitHub Actions.
Si la imagen que necesitás no tiene versión ARM, tenés dos caminos. El primero es construirla vos mismo en la Raspberry Pi con docker build -t mi_imagen_arm . (lento pero seguro, si tenés el Dockerfile). El segundo es usar emulación multi-arquitectura con QEMU, que te permite correr binarios amd64 sobre ARM —vas a pagar un costo de rendimiento, pero para desarrollo y pruebas zafa.
Activá la emulación multi-arquitectura con QEMU para imágenes amd64
QEMU es un emulador que, combinado con binfmt_misc del kernel de Linux, permite que binarios compilados para una arquitectura se ejecuten transparentemente en otra. Cuando lo configurás bien, Docker puede correr imágenes amd64 en tu Raspberry Pi sin que tengas que hacer malabares. El proceso, documentado en la fuente original, es así:
- Instalá los paquetes necesarios:
sudo apt-get install qemu-user-static binfmt-supporten tu Raspberry Pi. - Registrá los binarios QEMU en el kernel:
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes. Este contenedor hace la magia de configurarbinfmt_miscpara que el kernel sepa cómo manejar binarios de otras arquitecturas. - Verificá que funcione:
docker run --rm -it alpine uname -m. Si QEMU está activo, deberías verx86_64como arquitectura emulada.
¿El lado B de esta solución? La emulación es lenta. Muy lenta. Estás traduciendo cada instrucción x86 a ARM en tiempo real, así que no esperes correr bases de datos ni servicios pesados con esto. Para un contenedor liviano de pruebas o un script ocasional, funciona; para producción directamente no sirve y deberías construir imágenes nativas ARM.
Ejecutá en primer plano para ver los logs reales del error
El flag -d es cómodo, pero cuando algo falla, te esconde todo lo que necesitás saber. Si tu contenedor muere con exit code 1, sacale el -d y ejecutá en modo interactivo con -it, así: Lo explicamos a fondo en como vimos en la guía de hreflang.
docker run -it --rm mi_imagen
Ahora en vez de un seco exited (1) vas a ver el error real en la terminal. Los mensajes que suelen aparecer en Raspberry Pi son:
exec user process caused: no such file or directory: El binario dentro del contenedor está compilado para una arquitectura que el kernel no reconoce. Traducción: imagen amd64 en ARM sin QEMU.standard_init_linux.go:211: exec user process caused "exec format error": Mismo problema, distinto mensaje. El formato del binario no es compatible con la CPU.- Errores de dependencias faltantes como
libc.so.6 not found: La imagen base es demasiado minimalista o está rota para la variante ARM.
Si alguna vez configuraste un contenedor en una máquina virtual x86 y después lo pasaste a una Raspberry Pi sin rebuild, sabés exactamente de lo que hablo. El error es siempre el mismo y la solución también: o emulás con QEMU o recompilás para ARM.
Construí imágenes nativas ARM con docker buildx y olvidate del problema
El enfoque que realmente resuelve el 99% de los errores por arquitectura es usar docker buildx para construir imágenes multi-arquitectura desde el vamos. En lugar de rezar para que alguien haya publicado una build ARM de la imagen que necesitás, la generás vos mismo para las plataformas que te interesan:
docker buildx build --platform linux/arm/v7,linux/arm64,linux/amd64 -t mi_imagen:latest --push .
Este comando crea una imagen que funciona en Raspberry Pi de 32 bits (arm/v7), en los modelos de 64 bits (arm64) y en servidores x86 estándar. Docker se encarga de seleccionar la capa correcta según la arquitectura de la máquina donde se ejecute. ¿La contra? Necesitás un builder de buildx configurado (con docker buildx create --use alcanza) y acceso a un registry para pushear la imagen multi-arquitectura. Te puede servir nuestra cobertura de similar a lo que logramos con OpenClaw.
Para proyectos personales en una sola Raspberry Pi, muchas veces ni necesitás multi-arquitectura: con construir la imagen directamente en la Pi usando docker build -t mi_imagen . sin flag de plataforma ya te genera binarios nativos ARM. El buildx es indispensable cuando vas a distribuir la imagen o cuando tu flujo de CI/CD corre en máquinas x86 pero el target es ARM.
Comparativa de soluciones para exit code 1 en Raspberry Pi
| Solución | Complejidad | Rendimiento | ¿Sirve para producción? |
|---|---|---|---|
Corregir sintaxis (--net=host) | Baja | Nativo | Sí, si el error era ese |
| Usar imagen oficial ARM | Baja | Nativo | Sí |
| QEMU + binfmt_misc | Media | Lento (emulación) | No, solo desarrollo/pruebas |
| Rebuild nativo en Raspberry Pi | Media | Nativo | Sí |
| Buildx multi-arquitectura | Media-alta | Nativo en cada plataforma | Sí, ideal para distribución |
Errores comunes al solucionar docker run con exit code 1
- Asumir que la imagen de Docker Hub funciona en cualquier lado. Solo porque una imagen esté en Docker Hub no significa que tenga builds para ARM. Siempre chequeá la pestaña “Tags” y buscá variantes con sufijos
-arm,-arm64o el manifest multi-arch. - Olvidar el flag
--platformal hacer pull. Si tu máquina de desarrollo es x86 y hacésdocker pullahí, Docker baja la versión amd64. Cuando luego copiás esa imagen a la Raspberry Pi, se lleva la arquitectura incorrecta. Hacé el pull directamente en la Pi o forzá la plataforma con--platform linux/arm64. - No verificar permisos de dispositivos. Si tu contenedor necesita acceso a
/dev/mem,/dev/gpiomemo cualquier device del hardware de la Raspberry Pi, necesitás el flag--privilegedo mapear el dispositivo específico con--device. Sin eso, el proceso falla con exit code 1 y cero logs porque el acceso se deniega antes de que la aplicación pueda emitir un mensaje.
Un caso frecuente: una dependencia como libgl1 puede faltar en la imagen base ARM aunque esté presente en amd64, causando fallos difíciles de diagnosticar. La moraleja es que las builds multi-arquitectura no son mágicas: si tu Dockerfile asume cosas de la imagen base que cambian entre arquitecturas, el error se va a manifestar solo cuando probás en ARM.
Preguntas Frecuentes
¿Qué significa exit code 1 en Docker?
Es un código de salida genérico que indica que el proceso principal del contenedor terminó con un error. No es específico de Docker: cualquier programa en Linux devuelve un código al sistema operativo al finalizar, y el 1 es el valor estándar para “error genérico”. En el contexto de un contenedor, Docker simplemente te muestra el código que el proceso retornó.
¿Cómo saber si una imagen Docker es compatible con ARM?
Usá docker inspect --format '{{.Os}}/{{.Architecture}}' nombre_imagen para ver la arquitectura. Si devuelve linux/arm, linux/arm64 o muestra múltiples plataformas en el campo Manifests, la imagen soporta ARM. También podés revisar en Docker Hub: las imágenes con el badge “ARM” en la descripción o con tags que incluyen -arm64v8 suelen ser compatibles.
¿Por qué mi contenedor Docker se cierra inmediatamente en Raspberry Pi?
En la gran mayoría de los casos, porque el binario dentro del contenedor es para arquitectura x86_64 y tu Raspberry Pi usa ARM. El kernel detecta el formato incompatible, rechaza la ejecución y el proceso muere con exec format error. Eliminá el flag -d y ejecutá con -it para confirmar el mensaje de error exacto.
¿Qué es docker buildx y para qué sirve en Raspberry Pi?
Es una herramienta de Docker que permite construir imágenes para múltiples arquitecturas desde una misma máquina. En el contexto de Raspberry Pi, te sirve para generar una imagen que funcione tanto en ARM como en x86 sin tener que mantener Dockerfiles separados. Con un solo comando creás manifests multi-arquitectura que Docker Hub o tu registry privado entienden y distribuyen correctamente.
¿Conviene usar QEMU o rebuild nativo para correr imágenes amd64 en ARM?
Para desarrollo y pruebas rápidas, QEMU es práctico porque no requiere cambiar nada de la imagen. Pero el rendimiento cae drásticamente —estás emulando cada instrucción— así que para producción o cualquier cosa que use CPU intensivamente, siempre conviene hacer rebuild nativo en la Raspberry Pi o usar buildx para generar la variante ARM correcta. La diferencia de velocidad entre emulación y nativo puede ser de 10x según la carga, y en una Raspberry Pi cada ciclo de CPU cuenta.
Conclusión
El exit code 1 en Docker sobre Raspberry Pi es uno de esos errores que te hacen putear dos minutos y después, cuando lo entendés, no te vuelve a pasar. La causa raíz casi siempre es la misma: arquitectura incompatible entre la imagen y el procesador ARM de la Pi. Arrancá chequeando la sintaxis del comando (los espacios en --net = host son traicioneros), verificá la plataforma de la imagen con docker inspect, y si necesitás correr algo que solo existe en amd64, QEMU te salva las papas a costa de rendimiento. La solución definitiva, sobre todo si pensás distribuir tus contenedores, es aprender a usar docker buildx con soporte multi-arquitectura: cinco minutos de configuración te ahorran horas de debug en el futuro. Y si estás armando infraestructura con Docker sobre ARM y necesitás un entorno de cloud o VPS para pruebas más pesadas que las que banca una Raspberry Pi, podés chusmear opciones como los servicios de donweb.com que ya vienen con Docker preconfigurado en sus planes cloud.
