Troubleshooting

Häufige Probleme bei der Verwendung von Cuby und deren Lösungen.

Cuby startet nicht

Port 3847 ist belegt

Problem: Cuby kann nicht starten, weil Port 3847 bereits belegt ist.

Lösung:

1. Prüfen Sie, welcher Prozess den Port belegt:

   # macOS/Linux
   lsof -i :3847
    
   # Windows
   netstat -ano | findstr :3847

2. Beenden Sie den Prozess oder verwenden Sie die Umgebungsvariable PORT für einen anderen Port:

   PORT=3850 ./cuby

Installationsskript schlägt fehl

Problem: Die automatische Installation über das Studio schlägt fehl.

Lösung:

• Prüfen Sie die Internetverbindung (Zugriff auf marketplace.processcube.io)
• Prüfen Sie das Installationslog: ~/.processcube/cuby/install.log
• Versuchen Sie eine manuelle Installation

Produkt-Installation

Installation bleibt hängen

Problem: Ein Produkt wird installiert, aber der Fortschritt stoppt.

Lösung:

1. Prüfen Sie die Logs: ~/.processcube/products/<Produkt>/deploy.log
2. Starten Sie Cuby neu
3. Versuchen Sie die Installation erneut

npm-Fehler bei der Installation

Problem: Fehlermeldung zu npm-Paketen.

Lösung:

• Prüfen Sie, ob der API Key gültig ist (Marketplace → API Key)
• Prüfen Sie die Internetverbindung
• Löschen Sie den npm-Cache: ~/.processcube/products/<Produkt>/node_modules/ und installieren Sie erneut

Authority muss zuerst installiert werden

Problem: Engine oder LowCode können nicht gegen Authority konfiguriert werden.

Lösung: Installieren Sie die Produkte in der richtigen Reihenfolge:

1. Authority (Priorität 0)
2. Engine / LowCode (Priorität 1)
3. Weitere Produkte (Priorität 2+)

Studio findet Cuby nicht

Webview zeigt „Waiting for Cuby to start…”

Problem: Das Studio zeigt die Wartemeldung und Cuby wird nicht geladen.

Lösung:

1. Prüfen Sie, ob Cuby läuft: http://localhost:3847 im Browser öffnen
2. Falls nicht: Prüfen Sie ~/.processcube/cuby/ — ist Cuby installiert?
3. Starten Sie das Studio neu (der CubyManager versucht Cuby automatisch zu starten)
4. Prüfen Sie die Studio-Entwicklerkonsole (View → Toggle Developer Tools) auf Fehlermeldungen

Engines werden nicht synchronisiert

Problem: Im Studio erscheinen keine Engine-Verbindungen, obwohl Produkte in Cuby laufen.

Lösung:

1. Prüfen Sie den API-Endpoint: curl http://localhost:3847/api/processcubes
2. Die Antwort sollte ein Array mit ProcessCubeInfo-Objekten sein
3. Falls leer: Prüfen Sie, ob die Produkte in Cuby als „running” angezeigt werden
4. Warten Sie 10 Sekunden — das Studio pollt in diesem Intervall

Produkte laufen nicht

Produkt startet nicht

Problem: Ein Produkt wird als „gestoppt” angezeigt und lässt sich nicht starten.

Lösung:

1. Prüfen Sie die Logs: Produktverwaltung → Logs
2. Häufige Ursachen:
   • Port ist belegt (z.B. Port 8000 für Engine)
   • Fehlende Abhängigkeiten
   • Authority nicht erreichbar (für Engine/LowCode mit OAuth)
3. Prüfen Sie die Log-Dateien:
   • ~/.processcube/products/<Produkt>/start.log
   • ~/.processcube/products/<Produkt>/output.log

Produkt stürzt wiederholt ab

Problem: Ein Produkt wird gestartet, stürzt aber sofort wieder ab (Auto-Restart-Schleife).

Lösung:

1. Prüfen Sie output.log für Fehlermeldungen
2. Stoppen Sie das Produkt manuell (Dashboard → Produkt → Stop)
3. Prüfen Sie die Konfiguration
4. Bei Port-Konflikten: Produkt deinstallieren und mit anderem Port neu installieren

Port-Konflikte

Standard-Ports

Port bereits belegt

Wenn ein Standard-Port belegt ist, können Sie:

1. Den belegenden Prozess beenden
2. Das Produkt mit einem alternativen Port konfigurieren (über den Konfigurationsdialog bei der Installation)
3. Cuby’s Port-Manager reserviert automatisch den nächsten freien Port, wenn gewünscht

Logs und Diagnose

Log-Dateien

Cuby-API für Diagnose

# Health-Check
curl http://localhost:3847/api/health
 
# Konfiguration
curl http://localhost:3847/api/config
 
# Produkt-Status
curl http://localhost:3847/api/products/status
 
# ProcessCubes
curl http://localhost:3847/api/processcubes
 
# Logs eines Produkts
curl http://localhost:3847/api/products/<instanceId>/logs

Weitere Informationen

• Konfiguration — Konfigurationsdateien und Verzeichnisstruktur
• API-Referenz — Alle REST-Endpoints
• Produktverwaltung — Produkte starten, stoppen, Logs einsehen