故障排除

Common errors, their causes, and how to fix them. Each section lists the error message or symptom first, then what it means and what to do.

安装

uip: command not found after npm install -g

The npm global prefix is not on your PATH. Find it:

npm config get prefix

On macOS/Linux, add the returned prefix + /bin to your shell profile (~/.zshrc, ~/.bashrc). On Windows, %APPDATA%\npm should be on PATH by default — open a new terminal to pick up the update.

Full reference: Installing UiPath CLI — Troubleshooting.

EACCES: permission denied during install

You are trying to write to a system-owned npm prefix. Do not use sudo. Instead, set a user-local prefix:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @uipath/cli

身份验证

AuthenticationError (exit code 2) on every command

No valid session. Either:

• Run uip login to start an interactive session, or
• In CI, pass External App credentials: uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant "$UIPATH_TENANT", or
• For containers with a pre-issued token: set UIPATH_CLI_ENABLE_ENV_AUTH=true plus the UIPATH_CLI_AUTH_TOKEN / UIPATH_CLI_ORGANIZATION_* / UIPATH_CLI_TENANT_* variables.

Check status: uip login status.

See Authentication.

Token expired or Expired in uip login status

The refresh token is no longer valid — usually after weeks of inactivity or an admin-forced sign-out. Re-run uip login.

For env-var auth, the token is opaque to uip; rotate UIPATH_CLI_AUTH_TOKEN from the issuing side.

No tenant selected after uip login

The login completed without a tenant choice — either the picker was cancelled or --tenant was passed but the value doesn't match any accessible tenant. Retry with uip login --interactive to pick from a list, or uip login --tenant <exact-name>.

UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET env vars seem to be ignored

They are. UiPath CLI removed implicit env-var reading for these values. Pass explicitly:

uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant "$UIPATH_TENANT"

The env. prefix tells uip to resolve from the environment at runtime, without exposing the value on the command line.

工具

Tool '' not installed — attempting auto-install

Informational — the host is downloading a tool on first use. Subsequent calls reuse the installed copy. To avoid this log message in CI, pre-install:

uip tools install @uipath/orchestrator-tool @uipath/solution-tool

See Controlling tool auto-install.

Failed to auto-install ''

The tool download failed. Common causes:

• No network — check connectivity or proxy settings.
• Corporate proxy blocks npm — set HTTPS_PROXY=http://proxy.example.com:8080.
• npm registry not resolvable — verify npm config get registry points somewhere reachable.

Retry manually: uip tools install <verb>.

Tool commands vanish from uip --help after an upgrade

Tool version is out of step with the host. Fix:

uip tools update

This brings every installed tool to the latest version within the host's MAJOR.MINOR line. See Versioning and stability.

ValidationError: package '' is not on the whitelist

You tried to install a tool that isn't @uipath/. 1.x only supports the whitelisted set; third-party tools are not available yet.

Output and filtering

ValidationError: invalid --output-filter (exit 3)

The JMESPath expression couldn't be parsed. The CLI validates at parse time before running the command — fix the filter and retry. JMESPath reference: jmespath.org.

A common pitfall: --output-filter "Data.Jobs[0].Key" works, but --output-filter "Data.Jobs[-1].Key" does not — JMESPath [-1] is not supported. Use Data.Jobs | [-1:][0].Key instead, or post-process with jq.

I expected a table but got JSON

Default output is JSON. Pass --output table for the reading-friendly view. See Output formats.

Pipeline step fails to parse JSON — non-JSON text appears in stdout

Logs, progress bars, and some error messages go to stderr, not stdout. If something non-JSON is on stdout, you probably redirected both streams into the same file. Redirect them separately:

uip or folders list > folders.json 2> uip.log

Commands and exit codes

Command exits with 0 but I expected it to fail

A Success Result maps to exit code 0 even when the payload is empty. For example, uip or folders list --all --name Nonexistent exits 0 with Data: []. Branch on payload shape:

COUNT=$(uip or folders list --all --name Foo --output-filter "length(Data)" --output plain)
[[ "$COUNT" -eq 0 ]] && { echo "no match"; exit 1; }

uip tm wait exits with 2 — did auth fail?

No. tm wait reuses exit code 2 for timeout, not authentication. Check Result in the envelope to disambiguate (AuthenticationError vs TimeoutError). This domain-specific reuse is listed in Exit codes.

uip tm testset execute succeeded but my tests are failing

Correct by design. tm testset execute exits 0 once Orchestrator accepts the run — the verdict comes later. Chain the three-step idiom:

EXEC_ID=$(uip tm testset execute --test-set-key "$TESTSET" --output-filter "Data.ExecutionId" --output plain)
uip tm wait --execution-id "$EXEC_ID" --timeout 1800
FAILED=$(uip tm report get --execution-id "$EXEC_ID" --output-filter "Data.Failed" --output plain)
[[ "$FAILED" -gt 0 ]] && { echo "$FAILED tests failed"; exit 1; }

See Scripting patterns, uip tm testset, and uip tm execution.

配置

Environment variable changes don't take effect

A long-running process (an agent, a watched script) reads its environment once at startup. Restart the process after changing environment variables. For one-shot commands, a fresh uip invocation always reads the current environment.

Verify the precedence: CLI flag > environment variable > built-in default. See Configuration.

Shell completion

Tab completion doesn't complete

Open a new terminal after uip completion so the shell rc file is re-sourced. If still missing, run uip completion --print to see what block uip thinks is installed; compare against your ~/.zshrc / ~/.bashrc / $PROFILE.

uip or packages upload --package-name doesn't suggest names

Dynamic flag-value completion is zsh-only and needs jq on the PATH. Install jq or switch to zsh. Static subcommand + option-name completion works in all four shells regardless.

Shell and CI integration

CI step hangs on uip login or uip skills install

The command is waiting on an interactive prompt. Pass the necessary flags:

• uip login --tenant <name> (skip tenant picker)
• uip skills install --agent <name> (skip agent picker)

If you are not sure which prompt is interactive, run the failing command under uip --log-level debug … locally in a non-TTY context (redirect stdout) and inspect what prompt appeared.

uip or jobs start returns immediately — I wanted it to wait

By default jobs start accepts the run and exits. Add --wait-for-completion:

uip or jobs start <process-key> --wait-for-completion --timeout 600

Something I couldn't find here

Check the reference page for the command you're running — each has its own exit codes and examples section. Then search the release notes for a similar symptom. If nothing matches, gather:

• uip --version
• uip tools list
• The exact command and the full stderr / stdout
• The Result field from the JSON envelope

…and open an issue with the UiPath CLI team.

另请参阅

• Exit codes — what each code means, including the tm wait special case.
• Scripting patterns — retry, polling, stream separation, idempotent pipelines.
• Authentication — the three auth flows in detail.
• Installing UiPath CLI — Troubleshooting — install-specific errors.