Fehlerbehebung bei der UiPath-CLI

Wenn bei der Verwendung der UiPath-CLI Probleme auftreten, ziehen Sie die folgenden Problembehandlungsszenarien in Betracht.

Probleme im Zusammenhang mit der .NET -Version

Beschreibung:

Bei UiPath-CLI-Aufgaben und Pipelinevorgängen können Probleme auftreten, wenn die richtige Version des .NET -Frameworks nicht auf Ihrem System installiert ist (oder fehlt).

Wenn dieses Problem auftritt, können Fehlermeldungen auftreten wie:

  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]

oder

  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:

Sie müssen sicherstellen, dass Sie die richtige .NET -Version installiert haben.

Die Kompatibilitätsmatrix der CLI und der .NET -Version finden Sie im Abschnitt Voraussetzungen .

Probleme im Zusammenhang mit Sonderzeichen in Kennwörtern von Verbindungszeichenfolgen

In den meisten Fällen werden Verbindungskennwörter in einzelne Anführungszeichen (') eingeschlossen. Wenn das Kennwort jedoch Sonderzeichen wie ` oder $ enthält, ist ein anderer Ansatz erforderlich.

In diesen Fällen muss das Kennwort wie \`"<password>\`" formatiert werden, wobei <password> durch das tatsächliche Kennwort ersetzt wird. Zudem müssen Sie die Escape-Regeln der folgenden Tabelle einhalten:

Originalformat in ADUC	Escape-Format in PowerShell-Zeichenfolge
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$"

Beispiel:

Angenommen, das ursprüngliche Kennwort ist 7'8:<=XMe$y[@vC?_4ZeY8c-~y'W!1dU4gnczuf'/p>j<I. Gemäß Escape-Regeln für Sonderzeichen wird daraus: Password=\`"7'8:<=XMe`$y[@vC?_4ZeY8c-~y'W!1dU4```gnczuf'/p>```j<I\`".

Probleme im Zusammenhang mit einer langsamen Pipelineleistung

Beschreibung:

Beim Packen von Vorgängen in CI/CD-Pipelines kann die Leistung langsam sein. Die Verzögerung tritt typischerweise während der NuGet-Wiederherstellungsphase auf, in der die UiPath-CLI sowohl direkte als auch Transitiv-Aktivitätsabhängigkeiten auflöst.

Dieses Problem betrifft häufig gehostete CI-Agents (GitHub Actions, Azure DevOps, GitLab, Jenkins), die von einer sauberen Umgebung aus starten. Der globale NuGet-Paketcache bleibt nur dann zwischen Ausführungen erhalten, wenn er explizit konfiguriert ist. Dies erfordert für jeden Auftrag ein vollständiges Herunterladen aller Abhängigkeiten.

NuGet-Cache-Speicherorte:

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

Bewirkende Faktoren:

Wenn kein benutzerdefinierter nuget.config angegeben wird, fragt NuGet alle Standardquellen nacheinander ab:

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 überspringt keine langsamen oder nicht erreichbaren Feeds. Es wird auf eine Antwort oder ein Timeout gewartet, bevor mit der nächsten Quelle fortgefahren wird. Für jedes fehlende Paket führt NuGet die folgenden Schritte aus:

1. Eine Cache-Suche (leer bei neuen Agents).
2. Ein Test für jeden konfigurierten Feed in der richtigen Reihenfolge.
3. Eine Wartezeit oder eine Zeitüberschreitung, wenn ein Feed nicht reagiert.
4. Ein Download, nachdem eine erreichbare Quelle gefunden wurde.

Die Verzögerung skaliert mit der Anzahl der Abhängigkeiten. Ohne Cache wird dieser Prozess für jedes Paket bei jeder Pipelineausführung wiederholt.

Lösung:

So verbessern Sie die Wiederherstellungsleistung:

1. Verwenden Sie eine gekürzte nuget.config -Datei, die nur Feeds enthält, die vom Build-Agent aus erreichbar sind. Weitere Konfigurationsdetails finden Sie unter Verwalten von NuGet-Feeds .

2. Konfigurieren Sie die Cachepersistenz für den globalen Paketcache von NuGet zwischen Pipelineausführungen.

   Beispiel für 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. Verwenden Sie selbst gehostete Ausführungen mit persistentem Speicher, wenn die Umgebung dies erfordert.

Probleme im Zusammenhang mit der Verfügbarkeit der .NET-Laufzeit

Beschreibung:

Es können Probleme auftreten, bei denen die UiPath-CLI die .NET-Laufzeit auf Build-Agents nicht finden kann, was zu Fehlern wie:

dotnet is not recognized

Dieses Problem tritt auf, wenn das Dienstkonto, unter dem der Build-Agent ausgeführt wird, die Umgebungsvariable PATH der Maschine nicht erbt, auch wenn .NET ordnungsgemäß auf dem System installiert ist.

Lösung:

Sie müssen den .NET-Installationspfad explizit auf Pipeline-, Auftrags- oder Agent-Ebene definieren, bevor Sie CLI-Befehle ausführen.

Beispiel für Windows:

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

Hinweis:

Inline-Skriptänderungen an der PATH -Variablen werden nicht auf untergeordnete Prozesse übertragen. Der Pfad muss auf Pipeline-, Auftrags- oder Agent-Ebene konfiguriert werden, um sicherzustellen, dass die UiPath-CLI die .NET-Laufzeit sowohl in standardmäßigen als auch in benutzerdefinierten Installationsszenarien finden kann.

Probleme im Zusammenhang mit der Validierung von Proxy- und SSL-Zertifikaten

Beschreibung:

Beim Ausführen der UiPath-CLI in Unternehmensumgebungen mit SSL-überprüfenden Proxys können SSL-Zertifikatvalidierungsfehler auftreten. Häufige Fehlermeldungen sind:

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

Dieses Problem tritt auf, weil knotenbasierte Tools, einschließlich UiPath CLI und NuGet-Aufgaben, den Windows- oder Linux-Systemzertifikatspeicher nicht lesen, selbst wenn das Betriebssystem dem Zertifikat des Proxys vertraut.

Lösung:

So beheben Sie Probleme mit der Zertifikatvalidierung in Enterprise-Umgebungen:

1. Konfigurieren Sie Proxy-Umgebungsvariablen. Legen Sie die folgenden Variablen auf Pipeline-, Auftrags- oder Agent-Ebene fest, bevor eine CLI- oder Knotenaufgabe ausgeführt wird:

   HTTP_PROXY
   HTTPS_PROXY
   

   Dadurch wird sichergestellt, dass der Build-Agent und alle untergeordneten Prozesse die Proxykonfiguration erben.

2. Konfigurieren Sie die Zertifikatsvertrauenswürdigkeit für Node.js. Wenn der Proxy eine private oder selbstsignierte Zertifizierungsstelle (CA) verwendet, müssen Sie das Zertifikat der Zertifizierungsstelle im .pem -Format exportieren und Node.js so konfigurieren, dass es ihm vertraut:

   NODE_EXTRA_CA_CERTS=<path-to-pem>
   

   Beispiel für Windows:

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

   Node.js lädt diese Zertifikatsdatei beim Start, sodass HTTPS-Aufrufe ohne Zertifikatsfehler erfolgreich sind.

Wichtig:

Sie müssen diese Umgebungsvariablen auf Pipeline-, Auftrags- oder Agent-Ebene deklarieren. Wenn Sie sie innerhalb einzelner PowerShell- oder Bash-Skriptschritte festlegen, werden die Werte nicht an Node.js-Unterprozesse weitergegeben.

Probleme im Zusammenhang mit PowerShell-Parameterbehandlung

Sonderzeichen im Parameter „anwendungsGeheimnis“.

Beschreibung:

Wenn Sie den Parameter --applicationSecret in PowerShell-Skripten verwenden, können Sonderzeichen wie $, `, ! und andere zu Authentifizierungsfehlern oder unerwartetem Verhalten führen. Das liegt daran, dass PowerShell diese Zeichen als Sonderoperatoren interpretiert, wenn sie in doppelte Anführungszeichen eingeschlossen werden.

Beispielsweise behandelt PowerShell $ als Variablenerweiterungsoperator, sodass ein Geheimnis wie mySecret$123 in doppelten Anführungszeichen zu mySecret123 wird (wenn $123 undefiniert ist) oder durch einen unbeabsichtigten Wert ersetzt wird.

Häufige Symptome:

• Authentifizierungsfehler mit gültigen Anmeldeinformationen
• Fehler: „Nicht autorisiert“ oder „Ungültige Anmeldeinformationen“
• Inkonsistentes Verhalten, wenn derselbe Befehl in anderen Shells funktioniert

Lösung:

Verwenden Sie einfache Anführungszeichen ('') anstelle von doppelten Anführungszeichen (""), wenn Sie den Parameter --applicationSecret übergeben. Einfache Anführungszeichen verhindern, dass PowerShell Sonderzeichen interpretiert:

# 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"

Alternative Ansätze:

1. Speichern Sie Geheimnisse in Umgebungsvariablen:

   $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. Verwenden Sie die Geheimnisverwaltung der CI/CD-Plattform:

   • Azure DevOps: Geheime Pipelinevariablen
   • GitHub-Aktionen: Geheimnisse
   • Jenkins: Anmeldeinformations-Plugin

Tipp:

Dieses Problem tritt speziell bei PowerShell auf. In Bash, CMD oder anderen Shells gelten Standard-Anführungszeichenregeln.

Probleme im Zusammenhang mit der Authentifizierung

Fehler: „Unauthorized“ oder „403 Forbidden“

Beschreibung:

Beim Ausführen von UiPath-CLI-Befehlen, die mit dem Orchestrator interagieren, erhalten Sie möglicherweise Authentifizierungsfehler.

Mögliche Ursachen:

• Die ID oder der geheime Schlüssel der externen Anwendung ist falsch
• Erforderliche Scopes sind der externen Anwendung nicht zugewiesen
• Der mit dem Parameter -A angegebene Organisationsname stimmt nicht mit Ihrer Orchestrator-Organisation überein

Lösung:

• Überprüfen Sie die Anmeldeinformationen für die externe Anwendung im Orchestrator unter Administrator → Externe Anwendungen.
• Bestätigen Sie, dass alle erforderlichen Scopes der externen Anwendung zugewiesen sind. Die vollständige Liste der erforderlichen Scopes finden Sie unter Authentifizierung und Scopes .
• Stellen Sie sicher, dass der Organisationsname genau übereinstimmt (Groß-/Kleinschreibung wird beachtet).

Fehler: „Ungültiger Scope“

Beschreibung:

Es können Fehler auftreten, die darauf hinweisen, dass der angegebene Anwendungs-Scope ungültig ist oder nicht erkannt wird.

Mögliche Ursachen:

• Es werden falsche Scope-Namen verwendet.
• Orchestrator-Scopes und Lösungs-Scopes werden im selben Parameter gemischt.

Lösung:

• Verwenden Sie für Lösungsvorgänge die folgenden Scopes: AutomationSolutions, Solutions.Deployments, Solutions.Packages und ihre jeweiligen Unter-Scopes.
• Kombinieren Sie Orchestrator-Scopes (z. B. OR.Jobs) nicht mit Lösungs-Scopes im selben --applicationScope -Parameter.

Fehler: „Zertifikatsvalidierung fehlgeschlagen“

Beschreibung:

Beim Ausführen von CLI-Befehlen in Umgebungen mit Proxyservern können SSL-Zertifikatvalidierungsfehler auftreten.

Lösung:

• Konfigurieren Sie die Umgebungsvariable NODE_EXTRA_CA_CERTS , wie unter Probleme im Zusammenhang mit der Proxy- und SSL-Zertifikatsvalidierungbeschrieben
• Stellen Sie sicher, dass Proxyvariablen (HTTP_PROXY, HTTPS_PROXY) auf Pipeline- oder Agent-Ebene konfiguriert sind

Probleme im Zusammenhang mit Verpackung und Bereitstellung

Fehler: „Version ist erforderlich“

Beschreibung:

Dieser Fehler kann auftreten, wenn Sie versuchen, eine Lösung zu packen, ohne eine Versionsnummer anzugeben. Im Gegensatz zu eigenständigen Projekten erhöhen Lösungen ihre Version nicht automatisch.

Lösung:

Sie müssen den Parameter --version angeben, wenn Sie den Packbefehl ausführen:

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

Fehler: „Ungültiges Versionsformat“

Beschreibung:

Dieser Fehler tritt auf, wenn die Versionsnummer nicht dem erforderlichen Format der semantischen Versionierung entspricht.

Lösung:

Verwenden Sie das folgende Format: MAJOR.MINOR.PATCH (z. B. 1.0.0, 2.3.45)

Die folgenden Formate sind nicht gültig:

• 1.0 (fehlende Patch-Komponente)
• 1.0.0.0 (zu viele Komponenten)
• v1.0.0 (enthält ein nicht-numerisches Präfix)
• 1.0-beta (enthält Suffix)

Fehler: „Abhängigkeiten konnten nicht aufgelöst werden.“

Beschreibung:

Dieser Fehler weist darauf hin, dass die Abhängigkeiten der Lösung vor dem Packen nicht wiederhergestellt wurden.

Lösung:

Führen Sie den Befehl restore aus, bevor Sie versuchen, Folgendes zu packen:

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

Fehler: „Pfad nicht gefunden“

Beschreibung:

Der angegebene Lösungspfad kann nicht gefunden werden.

Lösung:

Stellen Sie sicher, dass der Parameter <solution-path> auf einen gültigen Lösungsordner oder eine gültige .uipx -Datei verweist.

Fehler: „Paket nicht gefunden“

Beschreibung:

Dieser Fehler tritt auf, wenn versucht wird, auf ein Lösungspaket zu verweisen, das nicht in Lösungen vorhanden ist.

Mögliche Ursachen:

• Das Paket wurde nicht erfolgreich hochgeladen.
• Der Paketname oder die Version ist falsch.
• Der Befehl zielt auf den falschen Mandanten oder die falsche Organisation ab.

Lösung:

• Stellen Sie sicher, dass das Paket mit uipcli solution upload-package hochgeladen wurde.
• Bestätigen Sie, dass der Paketname und die Version korrekt sind (beachten Sie, dass bei diesen Werten die Groß-/Kleinschreibung beachtet wird).
• Stellen Sie sicher, dass der Parameter -T den richtigen Mandanten angibt.

Fehler: „Ordner nicht gefunden“

Beschreibung:

Der angegebene Ordner ist in Orchestrator nicht vorhanden oder nicht zugänglich.

Mögliche Ursachen:

• Der Ordnername ist in Orchestrator nicht vorhanden.
• Unzureichende Berechtigungen für den Zugriff auf den Ordner.
• Der Ordner ist in einem anderen Mandanten vorhanden.

Lösung:

• Stellen Sie sicher, dass der mit dem Parameter -f angegebene Ordnername im Orchestrator vorhanden ist.
• Bestätigen Sie, dass Sie über die erforderlichen Berechtigungen für die Bereitstellung in diesem Ordner verfügen.
• Stellen Sie sicher, dass sich der Ordner im richtigen Mandanten befindet.

Fehler: „Bereitstellung ist bereits vorhanden“

Beschreibung:

Eine Bereitstellung mit dem angegebenen Namen ist bereits im Zielordner vorhanden.

Lösung:

• Verwenden Sie für jede Bereitstellung einen eindeutigen Bereitstellungsnamen (z. B. die Versionsnummer oder den Zeitstempel im Namen).
• Deinstallieren Sie die vorhandene Bereitstellung, bevor Sie eine neue erstellen. Weitere Informationen finden Sie unter Deinstallieren von Bereitstellungen.

Fehler: „Bereitstellung nicht gefunden“ (während der Aktivierung)

Beschreibung:

Dieser Fehler tritt auf, wenn versucht wird, eine Bereitstellung zu aktivieren, die nicht vorhanden ist.

Mögliche Ursachen:

• Der Befehl deploy wurde vor der Ausführung von deploy-activate nicht ausgeführt.
• Der Bereitstellungsname ist falsch.
• Der Bereitstellungsvorgang ist fehlgeschlagen.

Lösung:

• Vergewissern Sie sich, dass Sie uipcli solution deploy ausgeführt haben, bevor Sie uipcli solution deploy-activate ausführen.
• Bestätigen Sie, dass die Übereinstimmungsnamen genau übereinstimmen (beachten Sie, dass bei Bereitstellungsnamen die Groß-/Kleinschreibung beachtet wird).
• Überprüfen Sie die Befehlsausführungsprotokolle, um sicherzustellen, dass der Bereitstellungsvorgang erfolgreich abgeschlossen wurde.