Troubleshooting

Wo Sie nachsehen

• Launcher- und Runtime-Logs: <installDir>/logs/launcher.log und <installDir>/logs/runtime.log (Rotation bei 10 MB).
• Ausgabe des Autostart-Prozesses: ~/.edge-connector/stdout.log und ~/.edge-connector/stderr.log.
• Connector-Zustand: ~/.edge-connector/state.json.
• Auth-Token: ~/.edge-connector/auth-token.json — relative authTokenPath-Werte werden in dieses Verzeichnis aufgelöst; mit NARA_DATA_DIRECTORY verschieben Sie es.
• Live-Status: http://localhost:8080/statusz — zeigt Verbindungsstatus, letzten Verbindungsfehler und Webhook-Relay-Status.

Authentifizierungsfehler

No authentication token found. Run: edge-connector auth — der Connector hat kein gespeichertes Token. Führen Sie edge-connector auth aus und schließen Sie den Browser- oder Token-Flow ab.

Invalid token format - unable to decode JWT, Token has expired oder Token must include organization information (orgId or orgs) — das mit auth -t übergebene Token ist fehlerhaft, abgelaufen oder enthält keine Organisations-Claims. Besorgen Sie ein neues Token oder nutzen Sie den Browser-Flow (auth -b).

Timed out waiting for desktop auth — die Browser-Freigabe wurde nicht innerhalb des Freigabe-Zeitfensters abgeschlossen. Starten Sie den Flow erneut und klicken Sie zeitnah auf Approve. Enthält die Meldung last poll error, konnte der Connector die Plattform beim Abfragen nicht erreichen — prüfen Sie Firewall- und Proxy-Regeln für direkten HTTPS-Zugriff.

Tray zeigt „nicht angemeldet” und kein Browser öffnet sich — im Dienstmodus öffnet der Connector nie selbstständig einen Browser. Klicken Sie im Tray auf Login; die Anmeldeseite öffnet sich in der Sitzung, die geklickt hat.

[Connectivity] ... — nach fehlgeschlagenen Plattform-Anfragen prüft der Connector DNS, TCP und TLS getrennt und protokolliert, auf welcher Ebene die Verbindung stirbt. Meldungen über hängendes DNS, verworfene Pakete oder einen stehenden TLS-Handshake deuten auf eine Firewall oder Endpoint-Security hin, die den Dienstprozess blockiert; geben Sie die Zeile an das Netzwerk-Team weiter.

Runtime made no progress ... — der Watchdog hat eine festgefahrene Runtime erkannt und beendet; der Dienst startet sie automatisch neu. Prüfen Sie die zugehörige [Connectivity]-Zeile.

Verbindungsprobleme

Unable to connect to the Tool RPC server. — prüfen Sie, ob der Server erreichbar und die WebSocket-URL korrekt ist (toolRpcUrl in config.json oder die Umgebungsvariable TOOL_RPC_URL). Die Runtime versucht es mit Backoff erneut (5 s Basis, verdoppelnd, maximal 60 s, bis zu 10 Versuche).

Deployment already connected from another instance! — ein anderer Connector ist bereits mit derselben Deployment-Identität verbunden. Stoppen Sie die andere Instanz oder stellen Sie für diesen Rechner ein separates Deployment bereit.

Edge runtime already running (pid …) — eine Prozesssperre (<installDir>/edge-runtime.lock) zeigt eine laufende Runtime an. Beenden Sie den vorhandenen Prozess, bevor Sie einen neuen starten; nach einem Absturz entfernen Sie die verwaiste Lock-Datei.

Bundle- und Paketierungsfehler

No tool source files found in tools/... — der Packager erwartet eine Datei pro Tool unter tools/; ein einzelner index.ts-Einstiegspunkt wird nicht unterstützt. Erzeugen Sie die Vorlagen mit edge-connector generate neu.

Bundle too large: <n>MB (max 50MB) — das Bundle überschreitet das Upload-Limit. Entfernen Sie unnötige Abhängigkeiten oder Assets aus dem Implementierungsprojekt.

Launcher-Log-Einträge zu Rollback, No valid runtime available oder Download-/Entpackfehlern deuten auf ein fehlgeschlagenes Selbst-Update hin — der Launcher führt automatisch ein Rollback auf die vorherige Runtime durch; die Ursache finden Sie in launcher.log.

Fehler bei der Tool-Ausführung

Tool "<name>" is not available on this deployment — das Tool ist nicht Teil des diesem Deployment zugewiesenen Bundles. Prüfen Sie die Zuweisung mit edge-connector bundle status und bundle tools oder weisen Sie mit bundle assign das richtige Bundle zu.

requires execution context — das Tool benötigt einen Ausführungskontext, den der aktuelle Aufruf nicht bereitgestellt hat.