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 .

Ejecutar versiones anteriores de CLI en agentes CI/CD actualizados

Los entornos CI/CD alojados como Azure DevOps, GitHub Actions y GitLab Runners actualizan periódicamente sus imágenes de agente de compilación y eliminan los tiempos de ejecución .NET más antiguos que han llegado al final de su vida útil.

Si tu proceso utiliza una versión de CLI más antigua y el agente ya no proporciona el tiempo de ejecución .NET exacto para el que se creó la versión de CLI, CLI puede no iniciarse con un error como:

The framework 'Microsoft.NETCore.App', version 'X.0.0' was not found.

Esto no indica un problema del producto con UiPath CLI, sino más bien una falta de coincidencia en el tiempo de ejecución entre la compilación CLI y el entorno donde se ejecuta.

Resolución:

Para restaurar la compatibilidad, añade una política de avance en el archivo uipcli.runtimeconfig.json ubicado junto a uipcli.exe. Esto permite que la CLI se ejecute en tiempos de ejecución .NET más nuevos para los que se creó originalmente.

Localiza la versión del marco de destino para la que se creó tu CLI (comprueba el mensaje de error o el archivo uipcli.runtimeconfig.json existente si está presente) y luego crea o modifica el archivo de la siguiente manera:

{  "runtimeOptions": {    "tfm": "netX.0",    "framework": {      "name": "Microsoft.NETCore.App",      "version": "X.0.0",      "rollForward": "LatestMajor"    }  }}

Reemplaza X.0 con la versión del marco de destino (p. ej., net6.0, net8.0) y X.0.0 con la versión del runtime (p. ej., 6.0.0, 8.0.0).

La configuración "rollForward": "LatestMajor" permite a la CLI utilizar cualquier tiempo de ejecución .NET más reciente disponible en el agente.

Si tu entorno utiliza una ruta de instalación .NET personalizada, consulta la guía anterior sobre la configuración de DOTNET_ROOT y la verificación de la ubicación del runtime.

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.jsonhttps://pkgs.dev.azure.com/uipath/Public.Feeds/_packaging/UiPath-Official/nuget/v3/index.jsonhttps://gallery.uipath.com/api/v3/index.jsonhttps://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 chainThe 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_PROXYHTTPS_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 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.