故障排除

常见错误、原因以及修复方法。每个部分都首先列出了错误消息或症状，然后介绍了它的含义以及要执行的操作。

安装

uip：npm 安装 -g 后未找到命令

npm 全局前缀不在您的PATH上。查找内容：

npm config get prefix

在 macOS/Linux 上，将返回的前缀 + /bin添加到您的 Shell 配置文件中（ ~/.zshrc 、 ~/.bashrc ）。在 Windows 上， %APPDATA%\npm应默认为PATH — 打开一个新终端以获取更新。

完整参考：安装 UiPath CLI — 故障排除。

EACCES：安装过程中权限被拒绝

您正在尝试写入系统拥有的 npm 前缀。不要使用sudo 。相反，请设置用户本地前缀：

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

身份验证

每个命令都出现身份验证错误（退出代码 2）

无有效会话。它可以是：

• 运行uip login以启动交互式会话，或
• 在 CI 中，传递外部应用程序凭据： uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant "$UIPATH_TENANT" ，或
• 对于具有预先发出令牌的容器：设置UIPATH_CLI_ENABLE_ENV_AUTH=true并加上UIPATH_CLI_AUTH_TOKEN / UIPATH_CLI_ORGANIZATION_* / UIPATH_CLI_TENANT_*变量。

检查状态： uip login status 。

请参阅身份验证。

“令牌已过期”或 UIP 登录状态已过期

刷新令牌不再有效 — 通常在几周不活动或管理员强制退出后。重新运行uip login 。

对于 env-var 身份验证，令牌对uip不透明；从发行方轮换UIPATH_CLI_AUTH_TOKEN 。

uip 登录后未选择租户

登录已完成，但未选择租户 — 已取消选取器，或传递了--tenant ，但值与任何可访问的租户都不匹配。使用uip login --interactive重试以从列表中选择，或使用uip login --tenant <exact-name>重试。

UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET 环境变量似乎已被忽略

确实如此。UiPath CLI 删除了这些值的隐式 env-var 读取。显式传递：

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

env.前缀告知uip在运行时从环境中解析，而不会在命令行中公开值。

工具

工具”未安装 — 正在尝试自动安装

信息 — 主机正在下载首次使用的工具。后续调用将重用已安装的副本。为避免在 CI 中出现此日志消息，请预安装：

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

请参阅控制工具自动安装。

无法自动安装“ ”

工具下载失败。常见原因：

• 无网络— 检查连接或代理设置。
• 公司代理阻止 npm — 集HTTPS_PROXY=http://proxy.example.com:8080 。
• npm 注册表无法解析— 请验证npm config get registry点可访问的位置。

手动重试： uip tools install <verb> 。

升级后，工具命令从 uip --help 中消失

工具版本与主机不同步。修复：

uip tools update

这会将主机的 MAJOR.次要行中的每个已安装工具升级到最新版本。请参阅版本控制和稳定性。

验证错误：包“ “不在白名单中

您尝试安装@uipath/以外的工具。1.x 仅支持白名单集合；第三方工具尚不可用。

输出和筛选

验证错误：无效的 --output-filter（出口 3）

无法解析 JMESPath 表达式。CLI 在运行命令之前在解析时进行验证 — 修复筛选器并重试。JMESPath 参考： jmespath.org 。

常见错误： --output-filter "Data.Jobs[0].Key"有效，但--output-filter "Data.Jobs[-1].Key"无效 — 不支持 JMESPath [-1] 。改为使用Data.Jobs | [-1:][0].Key ，或使用jq进行后处理。

我预期会是表格，但收到 JSON 文件

默认输出为JSON 。对于便于读取的视图，传递--output table 。请参阅输出格式。

管道步骤无法解析 JSON — 标准输出中显示非 JSON 文本

日志、进度条和一些错误消息将发送到标准错误 (stderr) ，而不是标准输出 (stdout)。如果标准输出上包含非 JSON 的内容，则您可能将两个流重定向到同一个文件中。分别重定向：

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

命令和退出代码

命令以 0 退出，但我预计它会失败

即使有效负载为空， Success Result也会映射到退出代码0 。例如， uip or folders list --all --name Nonexistent使用0退出Data: [] 。根据有效负载形状进行分支：

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

uip tmwait 退出，返回码为 2 — 身份验证是否失败？

否。 tm wait重用退出代码2来超时，而非身份验证。选中信封中的Result以消除歧义（ AuthenticationError与TimeoutError ）。退出代码中列出了这种特定于域的重用行为。

uip tm 测试集运行成功，但我的测试失败

依据设计更正。Orchestrator 接受运行后， tm testsets run就会退出0 — 稍后才会出现结果。将三步成语连接起来：

EXEC_ID=$(uip tm testsets run --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; }

请参阅脚本模式、 uip tm 测试集和uip tm 执行。

配置

环境变量更改未生效

长时间运行的流程（智能体、监控的脚本）会在启动时读取一次其环境。更改环境变量后重新启动流程。对于一次性命令，新的uip调用始终会读取当前环境。

请验证优先级：CLI 标志 > 环境变量 > 内置默认值。请参阅配置。

Shell 补全

未完成制表符补全

在uip completion之后打开一个新终端，以便重新为 Shell rc 文件寻找来源。如果仍然缺少，请运行uip completion --print以查看uip认为已安装的块；与您的~/.zshrc / ~/.bashrc / $PROFILE进行比较。

uip 或 Packages upload --package-name不建议名称

动态标志值补全仅适用于 zsh ，并且需要jq上的PATH 。安装jq或切换到 zsh。无论何种方式，静态子命令 + 选项名称补全适用于所有四种 Shell。

Shell 和 CI 集成

CI 步骤在 UIP 登录或安装 UIP 技能时挂起

该命令正在等待交互式提示词。传递必要的标志：

• uip login --tenant <name> （跳过租户选取器）
• uip skills install --agent <name> （跳过智能体选取器）

如果您不确定哪个提示词是交互式的，请在非 TTY 上下文（重定向标准输出）中本地运行uip --log-level debug …下的失败命令，并检查出现的提示词。

UIP 或作业开始立即返回 — 我希望它等待

默认情况下， jobs start接受运行并退出。添加--wait-for-completion ：

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

我在此处找不到的内容

查看您正在运行的命令的参考页面，每个页面都有自己的退出代码和示例部分。然后在发行说明中搜索类似症状。如果没有匹配项，则收集：

• uip --version
• uip tools list
• 确切命令和完整的标准错误/标准输出
• JSON 信封中的Result字段

…向 UiPath CLI 团队提出问题。

另请参阅

• 退出代码— 每个代码的含义，包括tm wait特殊情况。
• 脚本模式— 重试、轮询、流分离、幂等管道。
• 身份验证— 三个身份验证流程的详细信息。
• 安装 UiPath CLI — — 故障排除— 安装特定错误。