[SOLUCIONADO] Error 'failed to solve: process did not complete successfully' en Docker Build

El error ERROR: failed to solve: process "/bin/sh -c..." did not complete successfully: exit code: 1 es uno de los fallos más frecuentes y frustrantes al compilar imágenes con Docker BuildKit (Buildx). Este mensaje no es el problema en sí mismo, sino un contenedor genérico que indica que una instrucción RUN dentro de tu Dockerfile falló y devolvió un código de salida distinto de cero.

Dado que BuildKit agrupa y oculta los registros secundarios por defecto en su interfaz interactiva, la causa real (un fallo en apt-get, un paquete npm corrupto, falta de memoria o incompatibilidad de arquitectura) suele quedar oculta en la consola.

La Solución Paso a Paso

1. 1

   Paso 1: Ejecutar la compilación en modo plano para ver el error real

   Por defecto, la interfaz TUI de BuildKit trunca los errores internos de los subprocesos. Fuerza la salida en texto plano sin usar la caché para identificar exactamente qué línea del script o gestor de paquetes provocó el fallo:

   BASH Copiar

   docker build --progress=plain --no-cache -t mi-imagen:latest .
   

   Examina las líneas inmediatamente anteriores al mensaje failed to solve. Allí verás el error original, como E: Unable to locate package, npm ERR! code ENOENT o un fallo de compilación de GCC/Python.

2. 2

   Paso 2: Desglosar comandos complejos en instrucciones individuales

   Si tu Dockerfile agrupa múltiples pasos en un solo comando:

   DOCKERFILE Copiar

   # Difícil de depurar si falla a mitad de ejecución
   RUN apt-get update && apt-get install -y python3-pip curl && pip install -r requirements.txt
   

   Separa temporalmente cada comando en una directiva RUN independiente para aislar con precisión cuál instrucción genera el código de error:

   DOCKERFILE Copiar

   RUN apt-get update
   RUN apt-get install -y python3-pip curl
   RUN pip install --no-cache-dir -r requirements.txt
   

   Una vez corregido el problema, puedes volver a unificarlos para minimizar las capas de la imagen final.

3. 3

   Paso 3: Blindar el contexto de construcción con .dockerignore

   Si el proceso se interrumpe con exit code: 137 (OOMKilled) o context canceled, la causa habitual es que Docker está intentando transferir gigabytes innecesarios al demonio. Crea un archivo .dockerignore en la raíz de tu proyecto:

   TEXT Copiar

   .git
   .github
   node_modules
   dist
   build
   *.log
   .env
   .venv
   

   Esto reduce drásticamente el tiempo de compilación y evita que binarios locales de arquitectura incompatible se mezclen con el entorno del contenedor.

4. 4

   Paso 4: Ajustar la compatibilidad de arquitectura y paquetes base

   Si utilizas procesadores ARM (Apple Silicon, Raspberry Pi) y despliegas en x86_64 (o viceversa), ciertas librerías binarias fallarán al compilar en /bin/sh. Especifica explícitamente la plataforma de destino o fija la distribución base:

   DOCKERFILE Copiar

   # Especificar plataforma explícita si hay dependencias binarias x86
   FROM --platform=linux/amd64 python:3.11-slim-bookworm
   
   WORKDIR /app
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   COPY . .
   CMD ["python", "app.py"]
   

Preguntas Frecuentes

¿Por qué obtengo exit code 100 durante apt-get install en Docker?

El código 100 en Debian/Ubuntu suele deberse a repositorios no sincronizados (falta ejecutar apt-get update en la misma directiva) o a versiones antiguas de Docker Engine que no soportan llamadas al sistema modernas de imágenes como Debian 12 Bookworm.

¿Qué diferencia hay entre usar docker build y docker buildx build?

Buildx es el generador moderno que utiliza el motor BuildKit. Soporta compilación paralela, caché avanzada y compilación multi-arquitectura, pero requiere el flag --progress=plain para mostrar trazas de error completas en terminales estándar.