Troubleshooting UiPath CLI

If you run into issues while using the UiPath CLI, consider the following troubleshooting scenarios.

Issues related to the .NET version

Description:

You may encounter issues with UiPath CLI tasks and pipeline operations if the correct version of the .NET framework is not installed (or missing) on your system.

When this issue occurs, you may come across error messages such as:

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]

or

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:

You must ensure that you have the correct .NET version installed.

For the CLI and .NET version compatibility matrix, refer to the Prerequisites section.

Issues related to special character in connection string passwords

In most instances, connection passwords are encapsulated within a single quotation mark ('). However, when the password includes special characters such as ` or $, a different approach is required.

In these cases, the password must be formatted as \`"<password>\`", replacing <password> with the actual password. Moreover, you must also adhere to the escape rules as detailed in the following table:

Original format in ADUC	Escaped format in PowerShell string
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$"

Example:

Assume that the original password is 7'8:<=XMe$y[@vC?_4ZeY8c-~y'W!1dU4gnczuf'/p>j<I. Adhering to the special character escape rules, it becomes: Password=\`"7'8:<=XMe`$y[@vC?_4ZeY8c-~y'W!1dU4```gnczuf'/p>```j<I\`".

Issues related to slow pipeline performance

Description:

You may experience slow performance during packaging operations in CI/CD pipelines. The delay typically occurs during the NuGet restore phase, where UiPath CLI resolves both direct and transitive activity dependencies.

This issue commonly affects hosted CI agents (GitHub Actions, Azure DevOps, GitLab, Jenkins) that start from a clean environment. The NuGet global package cache does not persist between runs unless explicitly configured, requiring a full download of all dependencies on each job.

NuGet cache locations:

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

Contributing factors:

When no custom nuget.config is provided, NuGet queries all default sources in sequence:

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 does not skip slow or unreachable feeds. It waits for a response or timeout before proceeding to the next source. For each missing package, NuGet performs:

1. A cache lookup (empty on fresh agents).
2. A probe of each configured feed in order.
3. A wait or timeout if a feed does not respond.
4. A download after a reachable source is found.

The delay scales with the number of dependencies. With no cache, this process repeats for every package on each pipeline run.

Remedy:

To improve restore performance:

1. Use a trimmed nuget.config file that includes only feeds reachable from the build agent. Refer to Managing NuGet feeds for configuration details.

2. Configure cache persistence for the NuGet global package cache between pipeline runs.

   Example for Azure DevOps (Windows agent):

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

3. Use self-hosted runners with persistent storage if the environment requires it.

Issues related to .NET runtime availability

Description:

You may encounter issues where UiPath CLI cannot locate the .NET runtime on build agents, resulting in errors such as:

dotnet is not recognized

This issue occurs when the service account running the build agent does not inherit the machine PATH environment variable, even if .NET is properly installed on the system.

Remedy:

You must explicitly define the .NET installation path at the pipeline, job, or agent level before executing any CLI commands.

Example for Windows:

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

Note:

Inline script changes to the PATH variable do not propagate to child processes. The path must be configured at the pipeline, job, or agent level to ensure UiPath CLI can locate the .NET runtime in both default and custom installation scenarios.

Issues related to proxy and SSL certificate validation

Description:

You may encounter SSL certificate validation errors when running UiPath CLI in enterprise environments with SSL-inspecting proxies. Common error messages include:

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

This issue occurs because Node-based tools, including UiPath CLI and NuGet tasks, do not read the Windows or Linux system certificate store, even when the operating system trusts the proxy's certificate.

Remedy:

To resolve certificate validation issues in enterprise environments:

1. Configure proxy environment variables. Set the following variables at the pipeline, job, or agent level before any CLI or Node task executes:

   HTTP_PROXYHTTPS_PROXY

   This ensures the build agent and all child processes inherit the proxy configuration.

2. Configure certificate trust for Node.js. If the proxy uses a private or self-signed certificate authority (CA), you must export the CA certificate in .pem format and configure Node.js to trust it:

   NODE_EXTRA_CA_CERTS=<path-to-pem>

   Example for Windows:

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

   Node.js will load this certificate file at startup, allowing HTTPS calls to succeed without certificate errors.

Important:

You must declare these environment variables at the pipeline, job, or agent level. Setting them within individual PowerShell or Bash script steps does not propagate the values to Node.js subprocesses.

Issues related to authentication

Error: "Unauthorized" or "403 Forbidden"

Description:

You may receive authentication errors when executing UiPath CLI commands that interact with Orchestrator.

Possible causes:

• The External Application ID or secret is incorrect
• Required scopes are not assigned to the External Application
• The organization name specified with the -A parameter does not match your Orchestrator organization

Remedy:

• Verify the External Application credentials in Orchestrator under Admin → External Applications.
• Confirm all required scopes are assigned to the External Application. Refer to Authentication and scopes for the complete list of required scopes.
• Ensure the organization name matches exactly (case-sensitive).

Error: "Invalid scope"

Description:

You may encounter errors indicating that the specified application scope is invalid or not recognized.

Possible causes:

• Incorrect scope names are being used.
• Orchestrator scopes and Solutions scopes are mixed in the same parameter.

Remedy:

• For Solutions operations, use the following scopes: AutomationSolutions, Solutions.Deployments, Solutions.Packages, and their respective sub-scopes.
• Do not mix Orchestrator scopes (such as OR.Jobs) with Solutions scopes in the same --applicationScope parameter.

Error: "Certificate validation failed"

Description:

SSL certificate validation errors may occur when executing CLI commands in environments with proxy servers.

Remedy:

• Configure the NODE_EXTRA_CA_CERTS environment variable as described in Issues related to proxy and SSL certificate validation
• Ensure proxy variables (HTTP_PROXY, HTTPS_PROXY) are configured at the pipeline or agent level

Issues related to packaging and deployment

Error: "Version is required"

Description:

You may encounter this error when attempting to pack a solution without specifying a version number. Unlike standalone projects, solutions do not auto-increment their version.

Remedy:

You must provide the --version parameter when executing the pack command:

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

Error: "Invalid version format"

Description:

This error occurs when the version number does not follow the required semantic versioning format.

Remedy:

Use the following format: MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.3.45)

The following formats are not valid:

• 1.0 (missing patch component)
• 1.0.0.0 (too many components)
• v1.0.0 (contains non-numeric prefix)
• 1.0-beta (contains suffix)

Error: "Could not resolve dependencies"

Description:

This error indicates that the solution's dependencies have not been restored prior to packaging.

Remedy:

Execute the restore command before attempting to pack:

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

Error: "Path not found"

Description:

The specified solution path cannot be located.

Remedy:

Verify that the <solution-path> parameter points to a valid Solution folder or .uipx file.

Error: "Package not found"

Description:

This error occurs when attempting to reference a solution package that does not exist in Solutions.

Possible causes:

• The package was not uploaded successfully.
• The package name or version is incorrect.
• The command is targeting the wrong tenant or organization.

Remedy:

• Verify the package was uploaded using uipcli solution upload-package.
• Confirm the package name and version are correct (note that these values are case-sensitive).
• Ensure the -T parameter specifies the correct tenant.

Error: "Folder not found"

Description:

The specified folder does not exist in Orchestrator or is not accessible.

Possible causes:

• The folder name does not exist in Orchestrator.
• Insufficient permissions to access the folder.
• The folder exists in a different tenant.

Remedy:

• Verify the folder name specified with the -f parameter exists in Orchestrator.
• Confirm you have the necessary permissions to deploy to this folder.
• Ensure the folder is located in the correct tenant.

Error: "Deployment already exists"

Description:

A deployment with the specified name already exists in the target folder.

Remedy:

• Use a unique deployment name for each deployment (for example, include the version number or timestamp in the name).
• Uninstall the existing deployment before creating a new one. Refer to Uninstalling deployments for details.

Error: "Deployment not found" (during activate)

Description:

This error occurs when attempting to activate a deployment that does not exist.

Possible causes:

• The deploy command was not executed prior to running deploy-activate.
• The deployment name is incorrect.
• The deployment operation failed.

Remedy:

• Verify you executed uipcli solution deploy before running uipcli solution deploy-activate.
• Confirm the deployment name matches exactly (note that deployment names are case-sensitive).
• Review the command execution logs to ensure the deployment operation completed successfully.