Skip to Content
CubyTroubleshooting

Troubleshooting

Häufige Probleme und deren Lösungen beim Betrieb von Cuby.

Port-Konflikte

Problem: Port 3847 bereits belegt

Error: Failed to start server on port 3847

Lösung:

# Prüfen welcher Prozess den Port belegt
lsof -i :3847          # macOS/Linux
netstat -ano | findstr 3847  # Windows
 
# Alternativen Port verwenden
PORT=8080 cuby

Problem: Plugin-Port belegt

Ein Plugin kann seinen gewünschten Port nicht reservieren.

Lösung: Plugins sollten cuby.reservePort() statt fester Ports verwenden. Cuby sucht automatisch einen freien Port, wenn der gewünschte belegt ist.

Node.js / fnm

Problem: Node.js-Installation im Setup-Wizard schlägt fehl

Mögliche Ursachen:

  • Keine Internetverbindung
  • Firewall blockiert Downloads von github.com (fnm) oder nodejs.org

Lösung:

  1. Internetverbindung prüfen
  2. Schritt im Setup-Wizard wiederholen
  3. Falls fnm bereits installiert ist: ~/.processcube/nodejs/.fnm/ prüfen

Problem: Plugin-Worker startet nicht

Error: Node.js not found

Lösung: Das verwaltete Node.js (v22) wurde nicht installiert. Den Setup-Wizard erneut durchlaufen oder prüfen ob ~/.processcube/nodejs/.fnm/node-versions/v22.21.1/ existiert.

Marketplace-Verbindung

Problem: Marketplace nicht erreichbar

Error: Failed to fetch products from marketplace

Mögliche Ursachen:

  • Keine Internetverbindung
  • MARKETPLACE_URL falsch konfiguriert
  • Marketplace-Server nicht erreichbar

Lösung:

# Marketplace-Erreichbarkeit prüfen
curl https://marketplace.processcube.io/public_api/check-api-key \
  -u beliebig:DEIN_API_KEY
 
# Erwartete Antwort: 200 OK

Problem: API Key ungültig

401 Unauthorized

Lösung:

  • API Key Format prüfen (UUID v4: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
  • API Key auf processcube.io/invoices  verifizieren
  • Trial-Lizenz erstellen falls kein Key vorhanden

Details zur Marketplace-Authentifizierung unter /marktplatz.

Plugin-Fehler

Problem: Plugin-Installation schlägt fehl

Lösung:

  1. Install-Log prüfen: ~/.processcube/products/<Produktname>/deploy.log
  2. npm-Fehler suchen (z.B. fehlende Dependencies, Registry-Probleme)
  3. Produkt deinstallieren und neu installieren

Problem: Plugin startet nicht

Lösung:

  1. Start-Log prüfen: ~/.processcube/products/<Produktname>/start.log
  2. Prozess-Ausgabe prüfen: ~/.processcube/products/<Produktname>/output.log
  3. In der Web-Oberfläche: Produkt-Detail → Live-Logs

Problem: Plugin crasht wiederholt

Cuby startet abgestürzte npx-Produkte automatisch nach 5 Sekunden neu. Der Neustart-Zähler in der Produkt-Detail-Ansicht zeigt die Anzahl der Neustarts.

Lösung:

  1. Crash-Ursache in den Logs identifizieren
  2. Konfiguration prüfen (Port-Konflikte, fehlende Services)
  3. Abhängigkeiten prüfen (Engine/LowCode muss laufen wenn benötigt)

Logs finden und lesen

Log-Dateien

Alle Logs liegen im Produktverzeichnis unter ~/.processcube/products/<Produktname>/:

DateiInhalt
deploy.logAusgabe der deploy()-Methode
start.logAusgabe der start()-Methode
output.logLaufende Prozess-Ausgabe (mit Zeitstempeln)

Live-Logs über API

# In-Memory-Logs (letzte 100 Zeilen)
curl http://localhost:3847/api/products/PRODUKT_ID/logs?limit=100
 
# Log-Datei (letzte 500 Zeilen)
curl http://localhost:3847/api/products/PRODUKT_ID/logfile?lines=500

Live-Logs über Socket.IO

socket.emit('subscribe:logs', { productId: 'PRODUKT_ID' });
socket.on('product:log', ({ productId, line }) => {
  console.log(line);
});

Konfigurationsprobleme

Problem: Konfiguration wird nicht übernommen

Lösung:

  1. Prüfen ob ~/.processcube/config.json korrekt ist
  2. Cuby neu starten
  3. Falls im Operator-Modus: ConfigMap und Secrets prüfen

Problem: Secret Store nicht verfügbar

Im lokalen Modus wird Bun.secrets verwendet, im Operator-Modus K8s Secrets. Beim ersten Start wird der API Key automatisch migriert.

Lösung: Cuby mit --version starten, um zu prüfen ob die Binary korrekt funktioniert.

Kubernetes Operator

Problem: Pods starten nicht

Lösung:

  1. kubectl describe pod <pod-name> für Details
  2. Kubernetes Secret processcube-api-key prüfen
  3. Image-Pull-Rechte prüfen (Marketplace Docker-Registry benötigt Auth)

Problem: Ingress nicht erreichbar

Lösung:

  1. Ingress-Controller prüfen (Traefik oder Nginx)
  2. Cert-Manager ClusterIssuer prüfen
  3. DNS-Einträge für den konfigurierten Hostname prüfen

Allgemeine Tipps

  • Cuby-Version prüfen: cuby --version
  • Konfiguration zurücksetzen: ~/.processcube/ löschen und Setup-Wizard erneut durchlaufen
  • Orphan-Prozesse: Cuby räumt beim Start automatisch verwaiste Prozesse auf (basierend auf running-pids.json)
  • Neuinstallation: Binary über das Installationsskript aktualisieren — bestehende Konfiguration bleibt erhalten
API-ReferenzPostgreSQL