Saltar al contenido

Proceso completado con código de salida 1: cómo depurarlo

Última actualización:

Error: Process completed with exit code 1. no es el error real. Es el aviso de GitHub de que un comando de un paso run devolvió un estado distinto de cero, y el paso falló. La causa está en las líneas del registro que aparecen encima. Esta página explica cómo localizar esas líneas, cómo reproducir el fallo y cuáles son las causas más frecuentes.

El mensaje exacto

Error: Process completed with exit code 1.

El código de salida 1 es el estado general de «algo ha ido mal». Muchas herramientas lo usan: los ejecutores de pruebas cuando una prueba falla, los linters cuando encuentran incidencias, grep cuando no encuentra coincidencias, npm cuando falla un script. Otros códigos tienen significados más concretos, como 137, 143, 127 y 128.

Paso 1: encontrar el error real

Expanda el paso que falla y lea hacia arriba desde la línea en rojo. El primer mensaje que parezca un error (una traza de pila, una prueba fallida, npm ERR!, error:) es la causa. Si el registro es largo, use el cuadro de búsqueda del visor de registros para error, fail y fatal.

Si no hay nada útil, active el registro de depuración. Vuelva a ejecutar el job y marque «Enable debug logging», o establezca el secreto o la variable del repositorio ACTIONS_STEP_DEBUG en true. En los pasos de shell, muestre cada comando al ejecutarse:

- name: Build
  run: |
    set -x
    npm ci
    npm run build

Paso 2: entender cómo ejecuta GitHub su script

Con shell: bash definido explícitamente, GitHub ejecuta bash --noprofile --norc -eo pipefail {0}. Sin un ajuste de shell en Linux, ejecuta bash -e {0}. En ambos casos el paso se detiene en el primer comando que falla y, con pipefail, un fallo en cualquier punto de una tubería hace fallar todo el paso. El código de salida del paso es el del comando que falló.

Causas habituales y soluciones

1. Falló un comando de prueba, lint o build

El caso más común. Ejecute el mismo comando en local, con la misma versión de Node, Python o Java que el workflow, y corrija lo que informe.

2. El lockfile no coincide

npm ci falla con código de salida 1 cuando package-lock.json y package.json no coinciden. Regenere el lockfile en local con npm install, haga commit y use en CI la misma versión del gestor de paquetes.

3. grep o diff no encontraron nada, o encontraron algo

grep termina con 1 cuando no hay coincidencias, y diff termina con 1 cuando los archivos difieren. Ambos son resultados normales que hacen fallar el paso. Si la ausencia de coincidencias es aceptable, indíquelo:

- run: grep -q "ready" status.txt || echo "not ready yet"

No añada || true a un comando cuyo fallo importe, porque oculta errores reales.

4. Falta una variable de entorno o un secreto

Los secretos llegan vacíos en workflows activados desde forks y en algunas ejecuciones de Dependabot, y los scripts que los necesitan fallan. Muestre si está definido, sin imprimir el valor:

- run: test -n "$API_TOKEN" || { echo "API_TOKEN is empty"; exit 1; }
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}

5. Funciona en local pero no en CI

Versiones de herramientas distintas, otro sistema operativo o nombres de archivo sensibles a mayúsculas. Fije las versiones con setup-node, setup-python o setup-java, y compruebe que las rutas de importación coincidan con la capitalización real de los archivos.

Si se espera un fallo

Use continue-on-error: true en un paso solo cuando realmente no quiera que falle el job, y compruebe su resultado después mediante steps.<id>.outcome.

Cómo prevenirlo

  1. Ejecute los mismos comandos en local con las mismas versiones, idealmente desde un único script que CI también invoque.
  2. Fije las versiones del runtime y de las herramientas en lugar de usar versiones flotantes.
  3. Muestre la versión de la herramienta que falla y el directorio de trabajo al inicio de cada job.
  4. Mantenga los pasos pequeños para que el paso que falla identifique el problema.
  5. No oculte los fallos con || true.

Preguntas frecuentes

¿Qué significa el código de salida 1 en GitHub Actions?

El comando devolvió el estado 1, el código general de fallo. GitHub marca el paso como fallido. Lo que salió mal está en la salida que aparece encima del mensaje.

¿Por qué no hay ningún error encima de «exit code 1»?

Es posible que la herramienta escribiera los errores en un archivo, o que un grupo de registro esté contraído. Expanda todos los grupos, active el registro de depuración y vuelva a ejecutar.

¿El código de salida 1 es lo mismo que el 0?

No. El código de salida 0 significa éxito. Cualquier otro código hace fallar el paso, salvo que establezca continue-on-error.

¿Puedo hacer que un paso ignore el código de salida 1?

Sí, con continue-on-error: true o gestionando el comando en el script. Hágalo solo cuando el fallo realmente no importe.