Bridge Fehlerbehebung

Wenn die Verbindung zwischen deinem FiveM-Server und Z-UCP nicht funktioniert, liegt das meist an einer Fehlkonfiguration. Hier sind die häufigsten Probleme und ihre Lösungen.

Häufige Fehlermeldungen

1. 401 Unauthorized

Ursache: Der API-Key in deiner config.lua ist ungültig oder gehört zu einem anderen Projekt. Lösung:

• Gehe im Z-UCP Admin Panel auf "Projekt-Einstellungen" -> "API-Key".
• Generiere einen neuen Key und kopiere ihn exakt in die config.lua.
• Stelle sicher, dass keine Leerzeichen vor oder nach dem Key vorhanden sind.

2. Connection Refused / Timeout

Ursache: Dein Server kann unsere API nicht erreichen (Firewall) oder die ApiUrl ist falsch. Lösung:

• Prüfe, ob Config.ApiUrl auf https://api.z-dev.app gesetzt ist.
• Stelle sicher, dass dein Server-Hoster ausgehende Verbindungen auf Port 443 (HTTPS) erlaubt.
• Teste die Verbindung manuell von deinem Server-Terminal: curl https://api.z-dev.app/api/v2/health.

3. Bridge Secret Mismatch

Ursache: Das Bridge-Geheimnis im Panel stimmt nicht mit dem auf dem Server überein. Lösung:

• Dieses Geheimnis wird automatisch generiert. Starte den Server neu, um einen neuen Handshake zu erzwingen.

Troubleshooting Checkliste

1. [ ] Ist das Plugin z-bridge in der server.cfg eingetragen (ensure z-bridge)?
2. [ ] Zeigt die Server-Konsole beim Start "Z-Bridge: Connected successfully" an?
3. [ ] Ist die IP deines Servers in den Z-UCP Einstellungen korrekt hinterlegt (Whitelist)?
4. [ ] Nutzt du die aktuellste Version des Bridge-Plugins?

Debug-Modus aktivieren

Wenn du das Problem nicht finden kannst, aktiviere den Debug-Modus in der config.lua:

Config.Debug = true

Starte den Server neu und schaue in die Datei z-bridge.log im Plugin-Ordner. Dort werden alle Requests und Fehlermeldungen im Detail protokolliert.

Support-Ticket eröffnen