UiPath CLI のトラブルシューティング

UiPath CLI の使用中に問題が発生した場合は、以下のトラブルシューティングをお試しください。

.NET のバージョンに関する問題

説明:

システムに正しいバージョンの .NET Framework がインストールされていない (または存在しない) 場合、UiPath CLI のタスクやパイプライン操作で問題が発生する可能性があります。

この問題が発生すると、次のようなエラー メッセージが表示されることがあります。

  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)

解決策:

正しいバージョンの .NET がインストールされていることを確認する必要があります。

CLI と .NET バージョンの相互運用性マトリクスについては、「 前提条件 」セクションをご覧ください。

接続文字列パスワードの特殊文字に関する問題

ほとんどの場合、接続パスワードは単一引用符 (') で囲みます。ただし、パスワードに ` や $などの特殊文字が含まれている場合は、別の方法が必要です。

このような場合、パスワードは \`"<password>\`" とフォーマットする必要があります。ここで、<password> は実際のパスワードに置き換えてください。さらに、次の表に示すエスケープ ルールにも従う必要があります。

ADUC の元の形式	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$"

例：

元のパスワードが 7'8:<=XMe$y[@vC?_4ZeY8c-~y'W!1dU4gnczuf'/p>j<I であるとします。特殊文字のエスケープ ルール規則に従うと、Password=\`"7'8:<=XMe`$y[@vC?_4ZeY8c-~y'W!1dU4```gnczuf'/p>```j<I\`" になります。

パイプラインのパフォーマンス低下に関する問題

説明:

CI/CD パイプラインでのパッケージ化操作中にパフォーマンスが低下する場合があります。遅延は通常、NuGet の復元フェーズ中に発生し、UiPath CLI がアクティビティの直接依存関係と推移的な依存関係の両方を解決します。

この問題は、通常、クリーンな環境から開始するホストされた CI エージェント (GitHub Actions、Azure DevOps、GitLab、Jenkins) に影響します。NuGet のグローバル パッケージ キャッシュは、明示的に設定されていない限り、実行間で保持されないため、各ジョブのすべての依存関係を完全にダウンロードする必要があります。

NuGet キャッシュの場所:

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

要因：

カスタム nuget.config が指定されていない場合、NuGet はすべての既定のソースに対して次の順序でクエリを実行します。

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

NuGet では、低速のフィードや到達できないフィードはスキップされません。応答またはタイムアウトを待ってから、次のソースに進みます。不足しているパッケージごとに、NuGet は以下を実行します。

1. キャッシュ検索 (新しいエージェントでは空)。
2. 構成された各フィードのプローブ。
3. フィードが応答しない場合の待機またはタイムアウト。
4. 到達可能なソースが見つかった後のダウンロード。

遅延は依存関係の数に応じて変化します。キャッシュを指定しない場合は、パイプラインを実行するたびに、すべてのパッケージに対してこのプロセスが繰り返されます。

解決策:

復元パフォーマンスを向上させるには:

1. ビルド エージェントから到達可能なフィードのみを含む、トリミングされた nuget.config ファイルを使用します。設定について詳しくは、「 NuGet フィードを管理する」をご覧ください 。

2. パイプライン実行間の NuGet グローバル パッケージ キャッシュのキャッシュ永続性を構成します。

   Azure DevOps (Windows エージェント) の例:

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

3. 環境で必要な場合は、永続ストレージを備えたセルフホスト ランナーを使用します。

.NET ランタイムの可用性に関する問題

説明:

UiPath CLI がビルド エージェントで .NET ランタイムを見つけられず、以下のようなエラーが発生する場合があります。

dotnet is not recognized

この問題は、.NET がシステムに適切にインストールされている場合でも、ビルド エージェントを実行しているサービス アカウントがコンピューター PATH 環境変数を継承しない場合に発生します。

解決策:

CLI コマンドを実行する前に、パイプライン、ジョブ、またはエージェント レベルで .NET のインストール パスを明示的に定義する必要があります。

Windows の例:

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

注:

インライン スクリプトで PATH 変数を変更しても、子プロセスには反映されません。既定のインストール シナリオとカスタム インストール シナリオの両方で UiPath CLI が .NET ランタイムを見つけられるように、パイプライン、ジョブ、またはエージェント レベルでパスを設定する必要があります。

プロキシと SSL 証明書の検証に関する問題

説明:

SSL 検査プロキシを使用するエンタープライズ環境で UiPath CLI を実行すると、SSL 証明書の検証エラーが発生することがあります。一般的なエラー メッセージは次のとおりです。

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

この問題は、オペレーティング システムがプロキシの証明書を信頼していても、UiPath CLI や NuGet タスクなどのノードベースのツールが Windows または Linux のシステム証明書ストアを読み取らないために発生します。

解決策:

エンタープライズ環境での証明書検証の問題を解決するには、次の手順を実行します。

1. プロキシ環境変数を設定します。CLI またはノード タスクを実行する前に、パイプライン、ジョブ、またはエージェント レベルで以下の変数を設定します。

   HTTP_PROXY
   HTTPS_PROXY
   

   これにより、ビルドエージェントとすべての子プロセスがプロキシ構成を継承するようになります。

2. Node.js の証明書信頼を構成します。プロキシでプライベート証明機関または自己署名証明機関 (CA) を使用している場合は、CA 証明書を .pem 形式でエクスポートし、それを信頼するように Node.js を設定する必要があります。

   NODE_EXTRA_CA_CERTS=<path-to-pem>
   

   Windows の例:

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

   Node.js は起動時にこの証明書ファイルを読み込むため、証明書エラーなしで HTTPS 呼び出しが成功します。

重要:

これらの環境変数は、パイプライン、ジョブ、またはエージェントレベルで宣言する必要があります。PowerShell または Bash スクリプトの個々のステップ内で設定しても、Node.jsサブプロセスに値が反映されません。

PowerShell パラメーターの処理に関する問題

applicationSecret パラメーターの特殊文字

説明:

PowerShell スクリプトで --applicationSecret パラメーターを使用する場合、 $、 `、 !などの特殊文字によって、認証の失敗や予期しない動作が発生する可能性があります。これは、PowerShell が二重引用符で囲まれた場合、これらの文字を特殊演算子として解釈するために発生します。

たとえば、PowerShell は $ を変数展開演算子として扱うため、二重引用符で囲まれた mySecret$123 のようなシークレットは mySecret123 ( $123 が定義されていない場合) になるか、意図しない値に置き換えられます。

一般的な症状:

• 有効な資格情報による認証の失敗
• エラー: 「認可されていません」または「資格情報が無効です」
• 同じコマンドが他のシェルで動作する場合の一貫性のない動作

解決策:

--applicationSecret パラメーターを渡すときは、二重引用符 ( ("") の代わりに一重引用符 ('') を使用します。一重引用符を使用すると、PowerShell で特殊文字が解釈されません。

# Correct - single quotes treat the string literally
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S 'mySecret$123!@#' `
  -o "MyFolder"

# Incorrect - double quotes allow variable expansion
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S "mySecret$123!@#" `
  -o "MyFolder"

別のアプローチ:

1. シークレットを環境変数に格納します。

   $env:APP_SECRET = 'mySecret$123!@#'
   uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
     -A "myOrg" `
     -I "app-id" `
     -S $env:APP_SECRET `
     -o "MyFolder"
   

2. CI/CD プラットフォームのシークレット管理を使用する:

   • Azure DevOps: パイプライン シークレット変数
   • GitHub Actions: シークレット
   • Jenkins: 資格情報プラグイン

ヒント:

この問題は PowerShell に固有の問題です。Bash、CMD、またはその他のシェルでは、標準の引用ルールが適用されます。

認証に関する問題

エラー: 「認可されていません」または「403 Forbidden」

説明:

Orchestrator を操作する UiPath CLI コマンドを実行すると、認証エラーが発生することがあります。

考えられる原因:

• 外部アプリケーションの ID またはシークレットが正しくありません
• 必要なスコープが外部アプリケーションに割り当てられていない
• -A パラメーターで指定した組織名が Orchestrator の組織と一致しません

解決策:

• [管理] → [外部アプリケーション] で Orchestrator の外部アプリケーションの資格情報を確認します。
• 必要なすべてのスコープが外部アプリケーションに割り当てられていることを確認します。必要なスコープの完全なリストについては、「 認証とスコープ 」をご覧ください。
• 組織名が完全に一致していることを確認します (大文字と小文字が区別されます)。

エラー: 「スコープが無効です。」

説明:

指定したアプリケーション スコープが無効または認識されないことを示すエラーが発生する場合があります。

考えられる原因:

• 誤ったスコープ名が使用されています。
• Orchestrator のスコープとソリューションのスコープは、同じパラメーターに混在しています。

解決策:

• ソリューションの操作では、 AutomationSolutions、 Solutions.Deployments、 Solutions.Packages、およびそれぞれのサブスコープを使用します。
• 同じ --applicationScope パラメーターに、Orchestrator のスコープ ( OR.Jobsなど) とソリューションのスコープを混在させないでください。

エラー: 「証明書の検証に失敗しました。」

説明:

SSL 証明書の検証エラーは、プロキシ サーバーのある環境で CLI コマンドを実行すると発生する可能性があります。

解決策:

• 「プロキシおよび SSL 証明書の検証に関する問題」の説明に従って、NODE_EXTRA_CA_CERTS 環境変数を設定します
• プロキシ変数 (HTTP_PROXY、 HTTPS_PROXY) がパイプライン レベルまたはエージェント レベルで設定されていることを確認します

パッケージ化とデプロイに関する問題

エラー: 「バージョンが必要です。」

説明:

このエラーは、バージョン番号を指定せずにソリューションをパッケージ化しようとしたときに発生することがあります。スタンドアロン プロジェクトとは異なり、ソリューションではバージョンは自動的にインクリメントされません。

解決策:

pack コマンドを実行する際は、 --version パラメーターを指定する必要があります。

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

エラー: 「バージョンの形式が無効です。」

説明:

このエラーは、バージョン番号が必要なセマンティック バージョン管理形式に従っていない場合に発生します。

解決策:

次の形式を使用します: MAJOR.MINOR.PATCH (例: 1.0.0, 2.3.45)

次の形式は 無効です。

• 1.0 (パッチ コンポーネントが欠落)
• 1.0.0.0 (コンポーネントが多すぎる)
• v1.0.0 (数字以外のプレフィックスを含む)
• 1.0-beta (サフィックスを含む)

エラー: 「依存関係を解決できませんでした。」

説明:

このエラーは、パッケージ化前にソリューションの依存関係が復元されていないことを示します。

解決策:

パックする前に restore コマンドを実行してください。

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

エラー: 「パスが見つかりません。」

説明:

指定されたソリューションのパスが見つかりません。

解決策:

<solution-path> パラメーターが有効なソリューション フォルダーまたは.uipx ファイルを指定していることを確認します。

エラー: 「パッケージが見つかりません。」

説明:

このエラーは、[ソリューション] に存在しないソリューション パッケージを参照しようとしたときに発生します。

考えられる原因:

• パッケージは正常にアップロードされませんでした。
• パッケージの名前またはバージョンが正しくありません。
• コマンドの対象が間違っているテナントまたは組織である。

解決策:

• uipcli solution upload-packageを使用してパッケージがアップロードされたことを確認します。
• パッケージの名前とバージョンが正しいことを確認します (これらの値では大文字と小文字が区別されることに注意してください)。
• -T パラメーターで正しいテナントが指定されていることを確認します。

エラー: 「フォルダーが見つかりません」

説明:

指定されたフォルダーは Orchestrator に存在しないか、アクセスできません。

考えられる原因:

• フォルダー名が Orchestrator に存在しません。
• フォルダーにアクセスするための権限が不十分です。
• フォルダーが別のテナントに存在する。

解決策:

• -f パラメーターで指定したフォルダー名が Orchestrator に存在することを確認します。
• このフォルダーにデプロイするために必要な権限があることを確認します。
• フォルダーが正しいテナントに配置されていることを確認します。

エラー: 「デプロイは既に存在します。」

説明:

指定した名前のデプロイがターゲット フォルダーに既に存在している場合

解決策:

• デプロイごとに一意のデプロイ名を使用します (たとえば、名前にバージョン番号やタイムスタンプを含めます)。
• 新しいデプロイを作成する前に、既存のデプロイをアンインストールしてください。詳しくは、「 デプロイをアンインストール する」をご覧ください。

エラー: 「デプロイが見つかりません」(アクティブ化中)

説明:

このエラーは、存在しないデプロイをアクティブ化しようとしたときに発生します。

考えられる原因:

• deploy コマンドは、 を実行する前に実行deploy-activate。
• デプロイ名が正しくありません。
• デプロイ操作に失敗しました。

解決策:

• 実行する前に uipcli solution deploy を実行した uipcli solution deploy-activateを実行します。
• デプロイ名が完全に一致することを確認します (デプロイ名では大文字と小文字が区別されることに注意してください)。
• コマンド実行ログを確認して、デプロイ操作が正常に完了したことを確認します。