Códigos de salida

Contrato de código de salida para UiPath CLI, que cubre cinco niveles (0 a 4) y el código 130 para la cancelación del usuario, con guía de scripting.

Cada invocación uip termina con un código de salida numérico. Los scripts y los procesos de CI se ramifican en estos códigos para distinguir el éxito, un error transitorio que vale la pena volver a intentar, un problema de credenciales que requiere atención humana y un mal uso de la línea de comandos.

Contrato

El código de salida está determinado por el campo Result en el sobre de salida del comando. El host asigna cada valor Result a un único código de salida:

Código de salida	Result valor(es)	Significado
0	Success	El comando se completó y se logró su intención.
1	Failure, ConfigError	Fallo genérico o un problema de configuración que la CLI puede detectar antes de llegar al servidor (falta un tenant, falta un archivo en el disco, etc.).
2	AuthenticationError	La sesión no está autenticada, el token ha caducado o Orchestrator ha rechazado las credenciales (401/403).
3	ValidationError	El comando se invocó con una entrada no válida: marcador desconocido, marcador con valor incorrecto, marcadores mutuamente excluyentes, --output-filter mal formado, etc.
4	TimeoutError	Una operación de larga duración ha superado su plazo. Emitido por uip tm perf-scenario execute --wait cuando transcurre su --timeout-sec ; el propio sobre dice Result: "Failure".

Además:

Código de salida	Origen	Significado
130	Convención de Shell (128 + SIGINT)	El usuario canceló una solicitud interactiva (Ctrl+C durante uip login, uip skills install, uip completion, etc.).

UiPath CLI no emite otros códigos de salida. Un valor fuera de esta tabla indica una terminación anormal (caída no detectada, proceso secundario descontrolado o el shell informando de una señal) y debe investigarse, no coincidir con el patrón.

Estabilidad

• 0, 1, 2, 3 son estables dentro de una versión MAYOR. Un comando que sale con 3 (validación) para una entrada determinada seguirá saliendo con 3 en los golpes MINOR y PATCH.
• 4 significa tiempo de espera. Solo uip tm perf-scenario execute --wait lo emite hoy; otros comandos de larga duración pueden empezar a hacerlo en una versión MENOR, por lo que los scripts ya deberían gestionar 4 como "tiempo de espera".
• Se pueden añadir nuevos códigos en una versión MAYOR, con aviso previo en las notas de la versión. El conjunto actual cubre todos los modos de fallo que UiPath CLI 1.x necesita.

Consulta Control de versiones y estabilidad para obtener un contrato de servidor más amplio.

Leer el código de salida en los scripts

bash/sh/zsh

uip or folders list
case $? in
  0)   echo "ok" ;;
  1)   echo "command failed" ;;
  2)   echo "not authenticated — run uip login" ;;
  3)   echo "bad input — check flags" ;;
  4)   echo "timed out" ;;
  130) echo "cancelled by user" ;;
  *)   echo "unexpected exit: $?" ;;
esac

set -e (o set -o errexit) aborta el script en cualquier salida distinta de cero. Este es el valor predeterminado común para CI; combínalo con trap o con el manejo por comando cuando necesites distinguir entre códigos:

set -euo pipefail

if ! uip or folders list --output json > folders.json; then
  case $? in
    2)  uip login ; uip or folders list --output json > folders.json ;;
    *)  exit $? ;;
  esac
fi

PowerShell

uip or folders list
switch ($LASTEXITCODE) {
    0   { Write-Host "ok" }
    1   { Write-Host "command failed" }
    2   { Write-Host "not authenticated" }
    3   { Write-Host "bad input" }
    4   { Write-Host "timed out" }
    130 { Write-Host "cancelled" }
    default { Write-Host "unexpected exit: $LASTEXITCODE" }
}

Acciones de GitHub

Cualquier salida distinta de cero en un paso run: hace que el trabajo falle de forma predeterminada. Para ramificar en códigos específicos, captura el código explícitamente:

- name: Query Orchestrator
  id: folders
  run: |
    uip or folders list --output json > folders.json
    echo "exit_code=$?" >> "$GITHUB_OUTPUT"
  continue-on-error: true

- name: Re-authenticate if expired
  if: steps.folders.outputs.exit_code == '2'
  run: uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant "$TENANT"
  env:
    UIPATH_CLIENT_ID: ${{ secrets.UIPATH_CLIENT_ID }}
    UIPATH_CLIENT_SECRET: ${{ secrets.UIPATH_CLIENT_SECRET }}
    TENANT: ${{ vars.UIPATH_TENANT }}

Coincidencia de códigos de salida con el sobre JSON

Cuando --output json está en vigor (valor predeterminado), el sobre contiene la misma información que el código de salida, más un mensaje legible por humanos:

{
  "Result": "ValidationError",
  "Message": "Unknown option '--folder-pth'. Did you mean '--folder-path'?",
  "Instructions": "Run 'uip or folders list --help' to see valid options."
}

Un proceso puede ramificarse en $? para decisiones rápidas (reintentar en 2, abortar en 3) y analizar el sobre para obtener la imagen completa del error (aparece el Message en un webhook de Slack, el ticket Instructions junto con el paso que falla, etc.).

Cada sobre de fallo también lleva ErrorCode y Retry — consulta Formatos de salida: el sobre. Son una señal más detallada que el código de salida solo: varios valores ErrorCode distintos (por ejemplo, not_found y rate_limited) pueden asignarse al mismo código de salida 1, pero solo uno de ellos merece la pena reintentar . Consulta Patrones de script: ramificación en ErrorCode y Reintentar.

Semántica específica del comando

Los códigos de salida son códigos de estado, no códigos de éxito. Un comando que informa Success con una carga útil Data que indica "no se encontraron resultados" sigue existiendo 0. Por ejemplo, uip or folders list --all --name DoesNotExist devuelve {"Data": [], …} y sale 0 — porque la consulta de la lista se realizó correctamente; la ausencia de coincidencias es un resultado válido, no un fallo.

Cuando un comando necesita distinguir "la operación se ha realizado correctamente" de "el resultado del dominio es positivo", así lo indica en su página de referencia:

• uip tm testsets run : siempre sale de 0 una vez que Orchestrator acepta la solicitud de ejecución de prueba y devuelve ExecutionId. El veredicto de aprobación/error proviene de una cadena uip tm wait + uip tm report get independiente; rama en Data.Failed en la salida del informe. uip tm wait emite el código de salida 2 en el tiempo de espera (una reutilización específica del dominio de la ranura de error de autenticación, anotada en las ejecuciones uip tmwait y uip tm).
• uip tm perf-scenario execute --wait: sale de 4 cuando transcurre --timeout-sec antes de que finalice la ejecución. La ejecución en sí continúa; vuelve a comprobarlo con perf-scenario results get.
• uip or jobs start --wait-for-completion — sale distinto de cero cuando el trabajo alcanza un estado terminal Faulted o Stopped . Sin --wait-for-completion, el comando sale de 0 tan pronto como Orchestrator acepte la solicitud, independientemente del resultado posterior del trabajo.

Consulta la página de referencia para cualquier comando en el que la semántica de "success" sea ambigua.

Ver también

• Opciones globales : los marcadores --output, --output-filter, --log-level, --log-file .
• Patrones de scripting : reintentos, sondeo, procesos idempotentes.
• Formatos de salida : la forma del sobre que refleja el código de salida.
• Versiones y estabilidad : cómo evoluciona el contrato del código de salida a través de los golpes de semver.