Troubleshooting

Edge Connector Support

Diese Seite behandelt die häufigsten Probleme beim Einrichten und Betreiben des Edge Connectors, zusammen mit Diagnoseschritten und oft gestellten Fragen.

Häufige Probleme

Verbindung verweigert

Symptom: Der Edge Connector loggt ECONNREFUSED oder kann sich nicht mit dem nara Platform Server verbinden.

Ursachen und Lösungen:

• Platform Server läuft nicht. Überprüfe, ob der Server gestartet und erreichbar ist.
• Falsche URL. Prüfe TOOL_RPC_URL in deiner Umgebung oder config.json. Produktion verwendet wss:// mit einem öffentlichen Hostnamen.
• Firewall oder Proxy blockiert. Stelle sicher, dass ausgehende WebSocket-Verbindungen auf dem Zielport erlaubt sind. Prüfe Unternehmens-Proxies, die möglicherweise kein WebSocket-Upgrade unterstützen.
• Port-Mismatch. Bestätige, dass der Platform Server auf dem in deiner URL angegebenen Port lauscht.

Authentifizierung fehlgeschlagen

Symptom: Token validation failed, Token has expired oder No authentication token found.

Ursachen und Lösungen:

• Token abgelaufen. JWT-Tokens haben eine Ablaufzeit. Authentifiziere dich erneut mit edge-connector auth --browser oder edge-connector auth --token <new-token>.
• Token-Datei fehlt. Prüfe, ob auth-token.json am in config.json oder AUTH_TOKEN_PATH angegebenen Pfad existiert. Überprüfe, ob der Pfad korrekt ist.
• Keine Organisation im Token. Der JWT muss einen orgId-Claim oder eine orgs-Map enthalten. Stelle sicher, dass du in der nara Webapp in einer Organisation eingeloggt bist, bevor du den Token generierst.
• Deployment-Anmeldedaten ungültig. Wenn du DEPLOYMENT_ID und DEPLOYMENT_SECRET verwendest, überprüfe beide Werte und ob das Deployment im Admin-Panel existiert.

Bundle-Sync fehlgeschlagen

Symptom: Bundle sync error oder Tools aktualisieren sich nach einem Upload nicht.

Ursachen und Lösungen:

• Nicht mit der Plattform verbunden. Der Bundle-Sync benötigt eine aktive WebSocket-Verbindung. Prüfe den Verbindungsstatus über curl http://localhost:8080/statusz.
• Kein Bundle zugewiesen. Überprüfe, ob deinem Deployment ein Bundle zugewiesen ist. Verwende edge-connector bundle list zur Prüfung. Setze ein Standard-Bundle mit edge-connector bundle set-default.
• Netzwerkproblem. Der Download kann durch intermittierende Konnektivität fehlschlagen. Der Sync wiederholt sich automatisch alle 10 Minuten.
• Checksummen-Mismatch. Wenn die lokale Checksumme bereits mit dem Server übereinstimmt, findet kein Download statt. Erzwinge einen Re-Sync, indem du die lokale manifest.json und das dist/-Verzeichnis löschst und dann neu startest.

Tool-Ausführungs-Timeout

Symptom: Tool-Aufrufe geben einen Timeout-Fehler zurück oder der Agent meldet, dass das Tool nicht geantwortet hat.

Ursachen und Lösungen:

• Langsame Implementierung. Überprüfe deinen Tool-Code auf blockierende Operationen, lange Netzwerkaufrufe oder Endlosschleifen. Erwäge, Timeouts für externe API-Aufrufe hinzuzufügen.
• Implementierungsfehler. Eine nicht behandelte Exception in deinem Tool-Code kann dazu führen, dass er hängt. Umschließe die gesamte Logik mit try/catch und gib strukturierte Fehlerobjekte zurück.
• Ressourcenerschöpfung. Prüfe CPU- und Speicherverbrauch auf dem Edge-Connector-Host. Ressourcenintensive Tools brauchen möglicherweise mehr Kapazität.

Health Check schlägt fehl

Symptom: GET /healthz gibt 503 zurück oder der Health-Endpunkt ist nicht erreichbar.

Ursachen und Lösungen:

• Port-Konflikt. Port 8080 wird möglicherweise von einem anderen Dienst verwendet. Setze einen anderen Port über die Umgebungsvariable HEALTH_PORT.
• Noch nicht verbunden. /healthz gibt 503 zurück, bis der Edge Connector sich erfolgreich mit dem Platform Server verbunden hat. Prüfe /statusz für Details.
• Prozess läuft nicht. Überprüfe, ob der Edge-Connector-Prozess aktiv ist. Suche nach der edge-runtime.lock-Datei.

Prozess-Lock-Konflikt

Symptom: Edge runtime already running (pid ...) beim Start.

Ursachen und Lösungen:

• Eine andere Instanz läuft. Pro Installationsverzeichnis kann nur eine Edge Connector Runtime laufen. Stoppe die bestehende Instanz, bevor du eine neue startest.
• Veraltete Lock-Datei. Wenn der vorherige Prozess abgestürzt ist, ohne aufzuräumen, kann die Lock-Datei veraltet sein. Lösche edge-runtime.lock aus dem Installationsverzeichnis und versuche es erneut.
• Mehrere Installationen. Wenn du mehrere Edge Connectors brauchst, verwende separate Installationsverzeichnisse und verschiedene Deployment-IDs.

WebSocket-Verbindungsabbrüche

Symptom: Häufige Disconnected from platform server-Meldungen in den Logs.

Ursachen und Lösungen:

• Instabiles Netzwerk. Der Edge Connector verbindet sich automatisch mit exponentiellem Backoff neu. Gelegentliche Verbindungsabbrüche bei unzuverlässigen Netzwerken sind normal.
• Proxy-Timeout. Manche Proxies schließen inaktive WebSocket-Verbindungen. Der 30-Sekunden-Heartbeat sollte das verhindern, aber aggressive Proxies brauchen möglicherweise Konfigurationsänderungen.
• Server-Neustart. Wenn der Platform Server neu startet (z.B. bei Deployments), werden alle Verbindungen getrennt. Der Edge Connector verbindet sich automatisch wieder.
• Deployment-Konflikt. Wenn sich eine andere Instanz desselben Deployments verbindet, kann der Server das Duplikat ablehnen. Suche in den Logs nach Deployment already connected.

Diagnoseschritte

Folge bei der Fehlersuche diesen Schritten, um Informationen zu sammeln und das Problem einzugrenzen.

1. Runtime-Logs prüfen

   Der Edge Connector gibt detaillierte Logs auf stdout aus. Achte auf Fehlermeldungen, Verbindungsstatusänderungen und Tool-Ausführungsergebnisse. Wichtige Log-Muster:

   • Connected to platform server — erfolgreiche Verbindung
   • Disconnected from platform server — Verbindung verloren
   • Token validation failed — Authentifizierungsproblem
   • Bundle sync error — Bundle-Download-Problem
   • Tool "..." invoked but not available — fehlende Implementierung

2. Authentifizierung überprüfen

   Bestätige, dass der Token gültig und die Organisation korrekt ist:

   edge-connector bundle list

   Wenn das einen Fehler zurückgibt, authentifiziere dich erneut:

   edge-connector auth --browser

3. Verbindung testen

   Prüfe, ob der Platform Server erreichbar ist:

   curl -v http://localhost:3001

   Für Statusdetails des Connectors nutze die Runtime-Health-Checks:

   curl http://localhost:8080/statusz

   Die Bedeutung der Health- und Status-Endpunkte findest du auf der Seite Runtime.

4. Health-Endpunkt prüfen

   # Liveness (läuft der Prozess?)
   curl http://localhost:8080/livez
   
   # Readiness (ist er verbunden und bereit?)
   curl http://localhost:8080/healthz
   
   # Vollständiger Status
   curl http://localhost:8080/statusz

5. Konfiguration inspizieren

   Überprüfe deine config.json und Umgebungsvariablen:

   • Ist toolRpcUrl korrekt?
   • Zeigt authTokenPath auf eine gültige Token-Datei?
   • Ist platformApiUrl für deine Umgebung gesetzt?
   • Sind DEPLOYMENT_ID und DEPLOYMENT_SECRET gesetzt (für Server-Modus)?

6. Lock-Datei prüfen

   Wenn die Runtime nicht starten will, prüfe auf einen veralteten Lock:

   cat edge-runtime.lock

   Wenn die aufgelistete PID kein laufender Prozess ist, lösche die Datei und versuche es erneut.

Häufig gestellte Fragen

Wie oft findet der Bundle-Sync statt?

Der Edge Connector prüft alle 10 Minuten per periodischem Poll auf Bundle-Updates. Zusätzlich kann der Platform Server eine Echtzeit-Benachrichtigung pushen, wenn eine neue Bundle-Version hochgeladen wird, was einen sofortigen Sync auslöst. Du musst den Edge Connector nicht neu starten, um neue Tool-Implementierungen zu übernehmen.

Kann ich mehrere Edge Connectors betreiben?

Ja, aber jede Instanz muss ein separates Installationsverzeichnis und eine andere Deployment-ID verwenden. Der Prozess-Lock (edge-runtime.lock) verhindert, dass mehrere Instanzen im selben Verzeichnis laufen. Jedem Deployment kann ein eigenes Bundle zugewiesen werden, sodass verschiedene Edge Connectors unterschiedliche Tool-Sets ausführen können.

Was passiert bei einem Verbindungsabbruch?

Der Edge Connector verbindet sich automatisch mit exponentiellem Backoff neu. Die initiale Wartezeit beträgt 5 Sekunden und verdoppelt sich bei jedem Versuch bis maximal 60 Sekunden. Nach der Reconnection werden die Tools erneut beim Platform Server registriert. Während der Unterbrechung schlagen Tool-Ausführungsanfragen für diesen Connector auf Plattformseite mit einem “Connector unavailable”-Fehler fehl.

Wie aktualisiere ich Tools auf einem laufenden Connector?

Lade eine neue Bundle-Version mit edge-connector upload hoch. Verbundene Edge Connectors erkennen das Update entweder durch eine servergepushte Benachrichtigung (sofort) oder beim nächsten periodischen Sync (innerhalb von 10 Minuten). Das Update wird atomar angewendet:

1. Neue Tool-Dateien werden in ein Staging-Verzeichnis heruntergeladen.
2. Das bestehende dist/-Verzeichnis wird mit dem Staging-Verzeichnis getauscht.
3. Der Tool-Executor lädt die Implementierungen aus den neuen Dateien neu.
4. Die Tools werden erneut beim Server registriert.

Kein Neustart nötig.

Welche Ports nutzt der Edge Connector?

Port	Protokoll	Richtung	Zweck
Platform Server (konfigurierbar, typisch 443)	WebSocket	Ausgehend	Verbindung zum nara Platform Server
8080 (konfigurierbar via HEALTH_PORT)	HTTP	Eingehend	Health-Check-Endpunkte (/livez, /healthz, /statusz)

Kann ich den Edge Connector in einem Docker-Container betreiben?

Ja. Setze EC_DISABLE_TRAY=1 und EC_DISABLE_AUTOSTART=1, da System Tray und OS-Level-Autostart in Containern nicht anwendbar sind. Verwende DEPLOYMENT_ID und DEPLOYMENT_SECRET zur Authentifizierung. Konfiguriere Kubernetes-Liveness- und Readiness-Probes auf /livez und /healthz am Health-Port.

Wie prüfe ich, welche Tools registriert sind?

Nach der Verbindung des Edge Connectors loggt er die Liste der registrierten Tools:

Registered tools: getSystemInfo, getResourceUsage, getTopProcesses

Du kannst auch den /statusz Health-Endpunkt prüfen oder den Bundle-Status ansehen:

edge-connector bundle status

Was ist die maximale Bundle-Größe?

Die maximale Bundle-Größe beträgt 50 MB. Dieses Limit wird beim Upload-Schritt durchgesetzt. Wenn dein Bundle dieses Limit überschreitet, reduziere die Anzahl der inline eingebetteten Abhängigkeiten oder teile Tools auf mehrere Bundles auf.

Hilfe bekommen

Wenn du ein Problem mit dieser Anleitung nicht lösen kannst:

Konfigurationsreferenz Alle Konfigurationsoptionen und ihre Standardwerte ansehen.

CLI-Referenz Befehlssyntax und verfügbare Optionen prüfen.

Runtime-Verhalten Startsequenz, Reconnection-Logik und Sync-Verhalten verstehen.

Tipp

Wenn du ein Problem meldest, füge die Ausgabe von curl http://localhost:8080/statusz, deine config.json (mit geschwärzten Secrets), die relevante Log-Ausgabe und die Edge-Connector-Version (edge-connector --version) bei.