Solução de problemas do UiPath CLI

Se você encontrar problemas ao usar o UiPath CLI, considere os seguintes cenários para a solução dos problemas.

Problemas relacionados à versão .NET

Descrição:

Você pode encontrar problemas com as tarefas do UiPath CLI e operações de pipeline se a versão correta da estrutura .NET não estiver instalada (ou ausente) no seu sistema.

Quando esse problema ocorre, você pode encontrar mensagens de erro 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]

ou

  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:

Você deve se certificar de ter a versão correta do .NET instalada.

Para a matriz de compatibilidade de versões de CLI e .NET , consulte a seção Pré-requisitos .

Problemas relacionados ao caractere especial em senhas da string de conexão

Na maioria das instâncias, as senhas de conexão são encapsuladas dentro de uma única aspa ('). No entanto, quando a senha inclui caracteres especiais, como ` ou $, é necessária uma abordagem diferente.

Nesses casos, a senha deve ser formatada como \`"<password>\`", substituindo <password> pela senha verdadeira. Além disso, você também deve aderir às regras de escape conforme detalhado na seguinte tabela:

Formato original no ADUC	Formato escapado na string do 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$"

Exemplo:

Presuma que a senha original seja 7'8:<=XMe$y[@vC?_4ZeY8c-~y'W!1dU4gnczuf'/p>j<I. Aderindo às regras de escape de caractere especial, ele se torna: Password=\`"7'8:<=XMe`$y[@vC?_4ZeY8c-~y'W!1dU4```gnczuf'/p>```j<I\`".

Problemas relacionados ao lento desempenho do pipeline

Descrição:

Você pode enfrentar um desempenho lento durante operações de empacotamento em pipelines de CI/CD. O atraso normalmente ocorre durante a fase de restauração do NuGet, em que a UiPath CLI resolve as dependências de atividades diretas e transitivas.

Esse problema geralmente afeta agentes de CI hospedados (GitHub Actions, Azure DevOps, GitLab, Jenkins) que começam em um ambiente limpo. O cache do pacote global NuGet não persiste entre execuções, a menos que explicitamente configurado, exigindo um download completo de todas as dependências em cada trabalho.

Locais de cache do NuGet:

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

Fatores colaboradores:

Quando nenhum nuget.config personalizado é fornecido, o NuGet consulta todas as origens padrão em sequência:

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

O NuGet não ignora feeds lentos ou inacessíveis. Espera por uma resposta ou tempo limite antes de prosseguir para a próxima origem. Para cada pacote ausente, o NuGet executa:

1. Uma pesquisa de cache (vazia em agentes novos).
2. Uma investigação de cada feed configurado em ordem.
3. Uma espera ou tempo limite se um feed não responder.
4. Um download depois que uma origem acessível é encontrada.

O atraso é escalonado com o número de dependências. Sem cache, esse processo se repete para todos os pacotes em cada execução de pipeline.

Soluções de problemas:

Para melhorar o desempenho da restauração:

1. Use um arquivo nuget.config cortado que inclui apenas feeds acessíveis a partir do agente de build. Consulte Gerenciando feeds NuGet para obter detalhes de configuração.

2. Configure a persistência de cache para o cache do pacote global NuGet entre as execuções de pipeline.

   Exemplo para o Azure DevOps (agente do Windows):

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

3. Use executores auto-hospedados com armazenamento persistente se o ambiente exigir isso.

Problemas relacionados à disponibilidade de runtime .NET

Descrição:

Você pode encontrar problemas nos quais o UiPath CLI não pode localizar o runtime .NET em agentes de compilação, resultando em erros como:

dotnet is not recognized

Esse problema ocorre quando a conta de serviço que executa o agente de compilação não herda a variável de ambiente PATH da máquina, mesmo que o .NET esteja instalado corretamente no sistema.

Soluções de problemas:

Você deve definir explicitamente o caminho de instalação do .NET no nível do pipeline, trabalho ou agente antes de executar qualquer comando de CLI.

Exemplo para o Windows:

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

Observação:

Alterações de script em linha na variável PATH não se propagam para processos filho. O caminho deve ser configurado no nível do pipeline, trabalho ou agente para garantir que o UiPath CLI possa localizar o runtime .NET em cenários de instalação padrão e personalizado.

Problemas relacionados à validação de proxy e certificado SSL

Descrição:

Você pode encontrar erros de validação de certificado SSL ao executar o UiPath CLI em ambientes corporativos com proxies de inspeção SSL. As mensagens de erro comuns incluem:

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

Esse problema ocorre porque as ferramentas baseadas em nó, incluindo as tarefas do UiPath CLI e do NuGet, não leem o armazenamento de certificados do sistema Windows ou Linux, mesmo quando o sistema operacional confia no certificado do proxy.

Soluções de problemas:

Para resolver problemas de validação de certificados em ambientes Enterprise:

1. Configure variáveis de ambiente de proxy. Defina as seguintes variáveis no nível do pipeline, trabalho ou agente antes que qualquer tarefa de CLI ou nó seja executada:

   HTTP_PROXY
   HTTPS_PROXY
   

   Isso garante que o agente de build e todos os processos filho herdem a configuração do proxy.

2. Configure a confiança do certificado para o Node.js. Se o proxy usar uma autoridade de certificação (CA) privada ou autoassinada, você deve exportar o certificado de CA no formato .pem e configurar o Node.js para confiar nele:

   NODE_EXTRA_CA_CERTS=<path-to-pem>
   

   Exemplo para o Windows:

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

   O node.js carregará esse arquivo de certificado na inicialização, permitindo que as chamadas HTTPS sejam bem-sucedidas sem erros de certificado.

Importante:

Você deve declarar essas variáveis de ambiente no nível do pipeline, trabalho ou agente. Configurá-los dentro de etapas de script individuais do PowerShell ou Bash não propaga os valores para os subprocessos do Node.js.

Problemas relacionados à autenticação

Erro: "Não autorizado" ou "403 Proibido"

Descrição:

Você pode receber erros de autenticação ao executar comandos do UiPath CLI que interagem com o Orchestrator.

Possíveis causas:

• O ID ou segredo do aplicativo externo está incorreto
• Os escopos necessários não estão atribuídos ao aplicativo externo
• O nome da organização especificado com o parâmetro -A não corresponde à sua organização do Orchestrator

Soluções de problemas:

• Verifique as credenciais de aplicativos externos no Orchestrator em Admin → Aplicativos externos.
• Confirme se todos os escopos necessários estão atribuídos ao aplicativo externo. Consulte Autenticação e escopos para obter a lista completa de escopos necessários.
• Certifique-se de que o nome da organização corresponda exatamente (com diferenciação de maiúsculas e minúsculas).

Erro: "Escopo inválido"

Descrição:

Você pode encontrar erros indicando que o escopo do aplicativo especificado é inválido ou não reconhecido.

Possíveis causas:

• Nomes de escopo incorretos estão sendo usados.
• Os escopos do Orchestrator e os escopos de soluções são mistos no mesmo parâmetro.

Soluções de problemas:

• Para operações de Soluções, use os seguintes escopos: AutomationSolutions, Solutions.Deployments, Solutions.Packages e seus respectivos subEscopos.
• Não combine escopos do Orchestrator (como OR.Jobs) com escopos de Soluções no mesmo parâmetro --applicationScope .

Erro: "Falha na validação do certificado"

Descrição:

Erros de validação de certificado SSL podem ocorrer ao executar comandos CLI em ambientes com servidores proxy.

Soluções de problemas:

• Configure a variável de ambiente NODE_EXTRA_CA_CERTS conforme descrito em Problemas relacionados à validação de certificados de proxy e SSL
• Certifique-se de que as variáveis de proxy (HTTP_PROXY, HTTPS_PROXY) estejam configuradas no nível do pipeline ou do agente

Problemas relacionados ao empacotamento e implantação

Erro: "A versão é necessária"

Descrição:

Você pode encontrar esse erro ao tentar empacotar uma solução sem especificar um número de versão. Ao contrário dos projetos independentes, as soluções não incrementam automaticamente sua versão.

Soluções de problemas:

Você deve fornecer o parâmetro --version ao executar o comando pacote:

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

Erro: "Formato de versão inválido"

Descrição:

Esse erro ocorre quando o número da versão não segue o formato de versionamento semântico necessário.

Soluções de problemas:

Use o seguinte formato: MAJOR.MINOR.PATCH (por exemplo, 1.0.0, 2.3.45)

Os seguintes formatos não são válidos:

• 1.0 (componente de patch ausente)
• 1.0.0.0 (componentes demais)
• v1.0.0 (contém prefixo não numérico)
• 1.0-beta (contém sufixo)

Erro: "Não foi possível resolver dependências"

Descrição:

Esse erro indica que as dependências da solução não foram restauradas antes do empacotamento.

Soluções de problemas:

Execute o comando restore antes de tentar empacotar:

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

Erro: "Caminho não encontrado"

Descrição:

Não é possível localizar o caminho da solução especificada.

Soluções de problemas:

Verifique se o parâmetro <solution-path> aponta para uma pasta de solução ou arquivo .uipx válido.

Erro: "Pacote não encontrado"

Descrição:

Esse erro ocorre ao tentar fazer referência a um pacote de solução que não existe em Soluções.

Possíveis causas:

• O pacote não foi carregado com sucesso.
• A versão ou o nome do pacote estão incorretos.
• O comando está segmentando o tenant ou a organização errado.

Soluções de problemas:

• Verifique se o pacote foi carregado usando uipcli solution upload-package.
• Confirme se o nome e a versão do pacote estão corretos (observe que esses valores diferenciam maiúsculas e minúsculas).
• Certifique-se de que o parâmetro -T especifique o tenant correto.

Erro: "Pasta não encontrada"

Descrição:

A pasta especificada não existe no Orchestrator ou não está acessível.

Possíveis causas:

• O nome da pasta não existe no Orchestrator.
• Permissões insuficientes para acessar a pasta.
• A pasta existe em um tenant diferente.

Soluções de problemas:

• Verifique se o nome da pasta especificado com o parâmetro -f existe no Orchestrator.
• Confirme se você tem as permissões necessárias para implantar nessa pasta.
• Certifique-se de que a pasta esteja localizada no tenant correto.

Erro: "A implantação já existe"

Descrição:

Uma implantação com o nome especificado já existe na pasta de destino.

Soluções de problemas:

• Use um nome de implantação exclusivo para cada implantação (por exemplo, inclua o número da versão ou o carimbo de data/hora no nome).
• Desinstale a implantação existente antes de criar uma nova. Consulte Desinstalação de implantações para obter detalhes.

Erro: "Implantação não encontrada" (durante a ativação)

Descrição:

Esse erro ocorre ao tentar ativar uma implantação que não existe.

Possíveis causas:

• O comando deploy não foi executado antes da execução de deploy-activate.
• O nome da implantação está incorreto.
• A operação de implantação falhou.

Soluções de problemas:

• Verifique se você executou uipcli solution deploy antes de executar uipcli solution deploy-activate.
• Confirme se o nome da implantação corresponde exatamente. Os nomes de implantação diferenciam maiúsculas e minúsculas.
• Revise os logs de execução de comando para garantir que a operação de implantação seja concluída com sucesso.