Solución de problemas de la CLI de UiPath

Si tienes problemas al utilizar la CLI de UiPath, considera los siguientes escenarios de solución de problemas.

Problemas relacionados con la versión .NET

Descripción:

Puedes encontrar problemas con las tareas de UiPath CLI y las operaciones de proceso si la versión correcta del marco .NET no está instalada (o falta) en tu sistema.

Cuando se produce este problema, puedes encontrarte con mensajes de error como:

  You must install or update .NET to run this application.
  App: C:\Program Files (x86)\UiPath CLI\UiPath.CLI.Windows.23.10.8894.39673\tools\uipcli.exe
  Architecture: x64
  Framework: 'Microsoft.NETCore.App', version '6.0.0' (x64)
  .NET location: C:\Program Files\dotnet
  The following frameworks were found:
  8.0.5 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  8.0.8 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

o

  An error occurred trying to start process 'dotnet' with working directory 'C:\Users\Public\UiPathDevOpsScripts\uipathcli-23.10\tools'. The system cannot find the file specified. Failed to run the command. UiPath.CommandLine.Exceptions.CommandException: Packaging failed due to one or more errors.
  Message: An error occurred trying to start process 'dotnet' with working directory 'C:\Users\Public\UiPathDevOpsScripts\uipathcli-23.10\tools'. The system cannot find the file specified.
  Error at: System.Diagnostics.Process.StartWithCreateProcess(ProcessStartInfo startInfo)

Remedy:

Debes asegurarte de tener instalada la versión correcta de .NET.

Para obtener la matriz de compatibilidad de la CLI y la versión .NET , consulta la sección Requisitos previos .

Problemas relacionados con el carácter especial en las contraseñas de la cadena de conexión

En la mayoría de los casos, las contraseñas de conexión se encapsulan entre comillas simples ('). Sin embargo, cuando la contraseña incluye caracteres especiales como ` o $, se requiere un enfoque diferente.

En estos casos, la contraseña debe formatearse como \`"<password>\`", reemplazando <password> por la contraseña real. Además, también debes cumplir las reglas de escape como se detalla en la siguiente tabla:

Formato original en ADUC	Formato de escape en la cadena PowerShell
cn=James $ Smith	"cn=James `$ Smith"
cn=Sally Wilson + Jones	"cn=Sally Wilson \+ Jones"
cn=William O'Brian	"cn=William O'Brian"
cn=William O`Brian	"cn=William O``Brian"
cn=Richard #West	"cn=Richard #West"
cn=Roy Johnson$	"cn=Roy Johnson$"

Ejemplo:

Supongamos que la contraseña original es 7'8:<=XMe$y[@vC?_4ZeY8c-~y'W!1dU4gnczuf'/p>j<I. Al adherirse a las reglas de escape de caracteres especiales, se convierte en: Password=\`"7'8:<=XMe`$y[@vC?_4ZeY8c-~y'W!1dU4```gnczuf'/p>```j<I\`".

Problemas relacionados con el rendimiento lento del proceso

Descripción:

Puedes experimentar un rendimiento lento durante las operaciones de empaquetado en los procesos de CI/CD. El retraso suele producirse durante la fase de restauración de NuGet, en la que UiPath CLI resuelve las dependencias de actividad tanto directas como transitivas.

Este problema suele afectar a los agentes de CI alojados (GitHub Actions, Azure DevOps, GitLab, Jenkins) que parten de un entorno limpio. La caché de paquetes global de NuGet no persiste entre ejecuciones a menos que se configure explícitamente, lo que requiere una descarga completa de todas las dependencias en cada trabajo.

Ubicaciones de caché de NuGet:

• Linux/macOS: ~/.nuget/packages
• Windows: %UserProfile%\.nuget\packages

Factores que contribuyen:

Cuando no se proporciona nuget.config personalizado, NuGet consulta todas las fuentes predeterminadas en secuencia:

https://api.nuget.org/v3/index.json
https://pkgs.dev.azure.com/uipath/Public.Feeds/_packaging/UiPath-Official/nuget/v3/index.json
https://gallery.uipath.com/api/v3/index.json
https://uipath.pkgs.visualstudio.com/Public.Feeds/_packaging/UiPath-Internal/nuget/v3/index.json

NuGet no omite fuentes lentas o inalcanzables. Espera una respuesta o un tiempo de espera antes de pasar al siguiente origen. Para cada paquete que falta, NuGet realiza:

1. Una búsqueda de caché (vacía en agentes nuevos).
2. Una sonda de cada fuente configurada en orden.
3. Una espera o tiempo de espera si una fuente no responde.
4. Una descarga después de encontrar una fuente accesible.

El retraso escala con el número de dependencias. Sin caché, este proceso se repite para cada paquete en cada ejecución de proceso.

Remedio:

Para mejorar el rendimiento de la restauración:

1. Utiliza un archivo nuget.config recortado que solo incluya fuentes accesibles desde el agente de compilación. Consulta Gestionar fuentes de NuGet para obtener más información sobre la configuración.

2. Configure la persistencia de la caché para la caché global del paquete NuGet entre ejecuciones de procesos.

   Ejemplo para Azure DevOps (agente de Windows):

   - task: Cache@2
     displayName: "NuGet Cache"
     inputs:
       key: 'nuget | "$(Agent.OS)" | packages'
       restoreKeys: |
         nuget | "$(Agent.OS)"
       path: '$(UserProfile)\.nuget\packages'
   

3. Utiliza ejecutores autoalojados con almacenamiento persistente si el entorno lo requiere.

Problemas relacionados con la disponibilidad de .NET Runtime

Descripción:

Puedes encontrar problemas en los que UiPath CLI no puede localizar el tiempo de ejecución .NET en agentes de compilación, lo que da como resultado errores como:

dotnet is not recognized

Este problema se produce cuando la cuenta de servicio que ejecuta el agente de compilación no hereda la variable de entorno PATH de la máquina, incluso si .NET está correctamente instalado en el sistema.

Remedio:

Debes definir explícitamente la ruta de instalación de .NET en el nivel de proceso, trabajo o agente antes de ejecutar cualquier comando CLI.

Ejemplo para Windows:

env:
  PATH: 'C:\Program Files\dotnet;$(PATH)'

Nota:

Los cambios del script en línea en la variable PATH no se propagan a los procesos secundarios. La ruta debe configurarse en el nivel de proceso, trabajo o agente para garantizar que UiPath CLI pueda localizar el tiempo de ejecución .NET tanto en escenarios de instalación predeterminados como personalizados.

Problemas relacionados con la validación de certificados SSL y proxy

Descripción:

Puedes encontrar errores de validación de certificados SSL al ejecutar UiPath CLI en entornos empresariales con proxies de inspección SSL. Los mensajes de error comunes incluyen:

self-signed certificate in certificate chain
The SSL connection could not be established, see inner exception

Este problema se produce porque las herramientas basadas en nodos, incluidas las tareas UiPath CLI y NuGet, no leen el almacén de certificados del sistema Windows o Linux, incluso cuando el sistema operativo confía en el certificado del proxy.

Remedio:

Para resolver problemas de validación de certificados en entornos empresariales:

1. Configura las variables de entorno del proxy. Establece las siguientes variables en el nivel de proceso, trabajo o agente antes de que se ejecute cualquier tarea CLI o Nodo:

   HTTP_PROXY
   HTTPS_PROXY
   

   Esto garantiza que el agente de compilación y todos los procesos secundarios hereden la configuración del proxy.

2. Configura la confianza del certificado para Node.js. Si el proxy utiliza una autoridad de certificación (CA) privada o autofirmada, debes exportar el certificado de CA en formato .pem y configurar Node.js para que confíe en él:

   NODE_EXTRA_CA_CERTS=<path-to-pem>
   

   Ejemplo para Windows:

   NODE_EXTRA_CA_CERTS=C:\agent\certs\myCA.pem
   

   Node.js cargará este archivo de certificado al inicio, permitiendo que las llamadas HTTPS se realicen correctamente sin errores de certificado.

Importante:

Debes declarar estas variables de entorno en el nivel de proceso, trabajo o agente. Establecerlos dentro de los pasos de script individuales de PowerShell o Bash no propaga los valores a los subprocesos de Node.js.

Problemas relacionados con la gestión de parámetros de PowerShell

Caracteres especiales en el parámetro ApplicationSecret

Descripción:

Al utilizar el parámetro --applicationSecret en los scripts de PowerShell, los caracteres especiales como $, `, ! y otros pueden provocar fallos de autenticación o comportamientos inesperados. Esto ocurre porque PowerShell interpreta estos caracteres como operadores especiales cuando están entre comillas dobles.

Por ejemplo, PowerShell trata $ como un operador de expansión variable, por lo que un secreto como mySecret$123 entre comillas dobles se convierte en mySecret123 (si $123 no está definido) o se reemplaza por un valor no deseado.

Síntomas comunes:

• Fallos de autenticación con credenciales válidas
• Error: "No autorizado" o "Credenciales no válidas"
• Comportamiento incoherente cuando el mismo comando funciona en otros shells

Remedio:

Utiliza comillas simples ('') en lugar de comillas dobles ("") al pasar el parámetro --applicationSecret . Las comillas simples evitan que PowerShell interprete caracteres especiales:

# Correct - single quotes treat the string literally
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S 'mySecret$123!@#' `
  -o "MyFolder"

# Incorrect - double quotes allow variable expansion
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S "mySecret$123!@#" `
  -o "MyFolder"

Enfoques alternativos:

1. Almacenar secretos en variables de entorno:

   $env:APP_SECRET = 'mySecret$123!@#'
   uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
     -A "myOrg" `
     -I "app-id" `
     -S $env:APP_SECRET `
     -o "MyFolder"
   

2. Utilizar la gestión de secretos de la plataforma CI/CD:

   • Azure DevOps: variables secretas del proceso
   • Acciones de GitHub: Secretos
   • Jenkins: complemento de credenciales

Consejo:

Este problema es específico de PowerShell. En Bash, CMD u otros shells, se aplican las reglas de entrecomillado estándar.

Problemas relacionados con la autenticación

Error: "No autorizado" o "403 Prohibido"

Descripción:

Puedes recibir errores de autenticación al ejecutar comandos CLI de UiPath que interactúan con Orchestrator.

Posibles causas:

• El ID o secreto de la aplicación externa es incorrecto
• Los ámbitos necesarios no están asignados a la aplicación externa
• El nombre de la organización especificado con el parámetro -A no coincide con su organización de Orchestrator

Remedio:

• Verifica las credenciales de la aplicación externa en Orchestrator en Admin → Aplicaciones externas.
• Confirme que todos los ámbitos necesarios estén asignados a la aplicación externa. Consulta Autenticación y ámbitos para ver la lista completa de ámbitos necesarios.
• Asegúrese de que el nombre de la organización coincida exactamente (distingue entre mayúsculas y minúsculas).

Error: "Ámbito no válido"

Descripción:

Puedes encontrar errores que indiquen que el ámbito de aplicación especificado no es válido o no se reconoce.

Posibles causas:

• Se están utilizando nombres de ámbito incorrectos.
• Los ámbitos de Orchestrator y los ámbitos de Soluciones se mezclan en el mismo parámetro.

Remedio:

• Para las operaciones de Soluciones, utiliza los siguientes ámbitos: AutomationSolutions, Solutions.Deployments, Solutions.Packages y sus respectivos subámbitos.
• No mezcles ámbitos de Orchestrator (como OR.Jobs) con ámbitos de Soluciones en el mismo parámetro --applicationScope .

Error: "Error de validación del certificado"

Descripción:

Pueden producirse errores de validación del certificado SSL al ejecutar comandos CLI en entornos con servidores proxy.

Remedio:

• Configura la variable de entorno NODE_EXTRA_CA_CERTS como se describe en Problemas relacionados con la validación de certificados SSL y proxy
• Asegúrese de que las variables de proxy (HTTP_PROXY, HTTPS_PROXY) estén configuradas en el nivel de proceso o agente

Problemas relacionados con el empaquetado y la implementación

Error: "Se requiere la versión"

Descripción:

Puedes encontrar este error al intentar empaquetar una solución sin especificar un número de versión. A diferencia de los proyectos independientes, las soluciones no incrementan automáticamente su versión.

Remedio:

Debes proporcionar el parámetro --version al ejecutar el comando pack:

uipcli solution pack <solution-path> --version 1.2.3 --output <output-folder>

Error: "Formato de versión no válido"

Descripción:

Este error se produce cuando el número de versión no sigue el formato de versionado semántico requerido.

Remedio:

Utiliza el siguiente formato: MAJOR.MINOR.PATCH (por ejemplo, 1.0.0, 2.3.45)

Los siguientes formatos no son válidos:

• 1.0 (falta un componente del parche)
• 1.0.0.0 (demasiados componentes)
• v1.0.0 (contiene un prefijo no numérico)
• 1.0-beta (contiene sufijo)

Error: "No se pudieron resolver las dependencias"

Descripción:

Este error indica que las dependencias de la solución no se han restaurado antes del empaquetado.

Remedio:

Ejecuta el comando restore antes de intentar empaquetar:

uipcli solution restore <solution-path> --restoreFolder <output-folder>
uipcli solution pack <solution-path> --version 1.2.3 --output <output-folder>

Error: "Ruta no encontrada"

Descripción:

No se puede localizar la ruta de solución especificada.

Remedio:

Comprueba que el parámetro <solution-path> apunta a una carpeta de solución o archivo .uipx válido.

Error: "Paquete no encontrado"

Descripción:

Este error se produce al intentar hacer referencia a un paquete de soluciones que no existe en Soluciones.

Posibles causas:

• El paquete no se ha cargado correctamente.
• El nombre o la versión del paquete es incorrecto.
• El comando está dirigido al tenant u organización incorrectos.

Remedio:

• Verifique que el paquete se haya cargado utilizando uipcli solution upload-package.
• Confirma que el nombre y la versión del paquete son correctos (ten en cuenta que estos valores distinguen entre mayúsculas y minúsculas).
• Asegúrate de que el parámetro -T especifica el tenant correcto.

Error: "Carpeta no encontrada"

Descripción:

La carpeta especificada no existe en Orchestrator o no es accesible.

Posibles causas:

• El nombre de la carpeta no existe en Orchestrator.
• Permisos insuficientes para acceder a la carpeta.
• La carpeta existe en un tenant diferente.

Remedio:

• Comprueba que el nombre de la carpeta especificada con el parámetro -f existe en Orchestrator.
• Confirme que tiene los permisos necesarios para implementar en esta carpeta.
• Asegúrate de que la carpeta se encuentra en el tenant correcto.

Error: "La implementación ya existe"

Descripción:

Ya existe una implementación con el nombre especificado en la carpeta de destino.

Remedio:

• Utiliza un nombre de implementación único para cada implementación (por ejemplo, incluye el número de versión o la marca de tiempo en el nombre).
• Desinstala la implementación existente antes de crear una nueva. Consulta Desinstalar implementaciones para obtener más información.

Error: "Implementación no encontrada" (durante la activación)

Descripción:

Este error se produce al intentar activar una implementación que no existe.

Posibles causas:

• El comando deploy no se ejecutó antes de ejecutar deploy-activate.
• El nombre de la implementación es incorrecto.
• Error en la operación de implementación.

Remedio:

• Comprueba que has ejecutado uipcli solution deploy antes de ejecutar uipcli solution deploy-activate.
• Confirma que el nombre de la implementación coincide exactamente (ten en cuenta que los nombres de las implementaciones distinguen entre mayúsculas y minúsculas).
• Revise los registros de ejecución de comandos para asegurarse de que la operación de implementación se haya completado correctamente.