Troubleshooting

Wenn etwas nicht so funktioniert, wie es soll, findest du hier die häufigsten Probleme und ihre Lösungen.

Bot ist offline / reagiert nicht in Discord

Prüfe in dieser Reihenfolge:

Läuft VirtueBot überhaupt? Auf dem Server virtuebot status ausführen.
Falls nicht: virtuebot restart. Wenn der Neustart fehlschlägt, sieh dir die Logs an: virtuebot logs.
Falls die Logs einen Fehler mit „Bot-Token" zeigen: der Token wurde im Discord Developer Portal zurückgesetzt. Den neuen Token in /opt/virtuebot/.env eintragen und virtuebot restart.
Falls der Bot läuft, aber im Discord trotzdem offline ist: prüfe im Discord Developer Portal unter Bot, ob die beiden privilegierten Intents (Server Members und Message Content) eingeschaltet sind.

Webpanel nicht erreichbar

Im Lokal-Modus (Adresse http://localhost:3000 oder http://<server-ip>:3000):

Auf dem Server virtuebot status ausführen — läuft der Bot überhaupt?
Bist du auf einem anderen Gerät im selben Netzwerk? Falls nein, brauchst du Cloudflare-Tunnel oder eigene Domain.
Firewall auf dem Server aktiv? Port 3000 müsste freigegeben sein.

Im Cloudflare-Tunnel-Modus:

Cloudflare zeigt „Error 1033" → Tunnel-Dienst läuft auf deinem Server nicht. Mit virtuebot logs prüfen.
„Bad Gateway" → Public-Hostname-Konfiguration zeigt auf den falschen Port. Im Cloudflare-Dashboard prüfen.

Im Reverse-Proxy-Modus:

DNS-Eintrag ist noch nicht durch. Auf einem anderen Gerät ping deine-domain.de oder einen Online-Dienst nutzen.
Caddy/nginx läuft nicht: sudo systemctl status caddy bzw. sudo systemctl status nginx.

Die Redirect-URL im Discord Developer Portal muss mit der Adresse deines Panels exakt übereinstimmen (inkl. https:// und ohne abschließenden Schrägstrich).
Pfad muss /api/auth/callback/discord lauten.
Mehrere Redirect-URLs im Developer Portal sind erlaubt — z. B. eine für lokal und eine für deine Tunnel-Domain.

Willkommen, Auto-Moderation oder Reaktionsrollen reagieren nicht

Prüfe in dieser Reihenfolge:

Unter Einstellungen → Verwaltung ist der Master-Schalter für den jeweiligen Bereich aktiv.
Im jeweiligen Bereich ist die Konfiguration auch dort aktiv geschaltet (z. B. der „Aktiv"-Schalter beim Willkommens-Modul).
Der Bot hat die nötigen Rechte auf dem Discord-Server. Wenn du beim Einladen Administrator vergeben hast, sollte alles da sein. Wenn du die Rechte einzeln vergeben hast: vergleich mit der Liste in Discord-Anwendung anlegen, Abschnitt „Berechtigungen einzeln vergeben".

Reaktionsrollen-Nachricht wurde im Discord gelöscht

Im Setup-Editor auf „Veröffentlichen" klicken. VirtueBot legt die Nachricht neu an.

Auto-Rolle wird nicht vergeben

Damit VirtueBot eine Rolle vergeben darf, muss in der Discord-Rollenhierarchie seine eigene Rolle über der zu vergebenden Rolle stehen. Zusätzlich braucht er die Berechtigung „Rollen verwalten".

So passt du das an:

Im Discord-Server unter Servereinstellungen → Rollen den Bot-Eintrag suchen.
Mit der Maus an den linken Rand des Rollen-Eintrags fahren und ihn über die zu vergebende Rolle ziehen.

Geplante Nachricht läuft nicht

In der Übersicht steht der Status der letzten Ausführung. Häufige Ursachen:

Kein Schreibrecht im gewählten Channel.
Channel wurde gelöscht.
Die Nachricht ist pausiert (in der Übersicht erkennbar am Status).

Voice-Channel wird nicht angelegt

VirtueBot braucht „Kanäle verwalten" und „Mitglieder bewegen" auf dem Server. Die im Lobby-Template gewählte Kategorie muss existieren.

Musik bricht plötzlich ab oder wird verzerrt

Wenn dein Server zu wenig RAM hat, kann die Audio-Verarbeitung stocken. Empfohlen sind 6 GB RAM.
Bei Songs von YouTube: manchmal sperrt YouTube den Zugriff kurzzeitig (z. B. bei sehr neuen Videos). Versuch's nach 5 Minuten nochmal.
Internet-Verbindung deines Servers prüfen — bei Schwankungen kann ein Stream abreißen.

Spotify-Link wird nicht akzeptiert

Wenn die Meldung „Spotify-Link erkannt, aber Spotify-Verbindung fehlt" kommt: dein Server hat die Spotify-Zugangsdaten nicht hinterlegt. Anleitung zum Nachtragen unter Installation → Spotify nachträglich einrichten.
Wenn der Link akzeptiert wird, aber der falsche Song läuft: VirtueBot sucht den passenden Titel auf YouTube. Bei seltenen Tracks oder Live-Versionen kann das Ergebnis abweichen — alternativ den Song direkt per YouTube-Link oder Suchbegriff angeben.

Lizenz wird nicht erkannt

Im Panel unter Globale Einstellungen → Lizenz sehen, was der aktuelle Status ist.
Wenn die Meldung „Lizenz bereits auf anderer Instanz aktiv" kommt: du hast die Lizenz an einer anderen Stelle aktiviert. Dort musst du sie zuerst deaktivieren, bevor sie auf der neuen Instanz funktioniert.
Wenn die Meldung „Lizenz-Server nicht erreichbar" kommt: meist nur kurzzeitig. Der Bot bleibt im Paid-Modus, bis zur Lizenz-Erneuerung (im Hintergrund alle paar Tage) eine erfolgreiche Antwort kommt.

Nützliche Befehle

virtuebot status     # läuft alles?
virtuebot logs       # letzte 100 Zeilen aus den Logs
virtuebot restart    # neu starten ohne Datenverlust
virtuebot backup     # Datensicherung erstellen
virtuebot update     # auf neueste Version aktualisieren

Wenn nichts hilft

Wenn du nicht weiterkommst, melde dich:

Per Email an support@virtuebot.eu mit:
- einer kurzen Beschreibung des Problems
- der Ausgabe von virtuebot status
- den letzten Zeilen aus virtuebot logs (Geheimnisse wie Token vorher entfernen)
Im Discord-Server der Community (Link siehe Footer auf https://virtuebot.eu)

Je konkreter du beschreibst, was du gemacht hast und was nicht geht, desto schneller können wir helfen.