Fehler 2022: Server-seitige ICE-Verbindung fehlgeschlagen

Fehler 2022 (app.sfu.serverIceConnectionFailed2022) tritt auf, wenn der BigBlueButton-Medienserver (mediasoup oder Kurento) zwar ICE-Kandidaten ermittelt und dem Browser mitgeteilt hat, aber anschließend alle ICE-Verbindungsprüfungen scheitern. Im Gegensatz zu Fehler 2021, der bereits während der Kandidatenermittlung auftritt, hat der Server bei Fehler 2022 die Gathering-Phase erfolgreich abgeschlossen – der UDP-Pfad zwischen Server und Client lässt sich jedoch nicht aufbauen.

Wie äußert sich der Fehler?

Benutzer sehen eine Fehlermeldung im Browser und können weder Mikrofon noch Kamera oder Bildschirmfreigabe aktivieren. Der Verbindungsaufbau schlägt nach wenigen Sekunden fehl, ohne dass Audio oder Video übertragen wird. Die Fehlermeldung enthält den Code 2022 und erscheint sowohl beim Beitreten mit Audio als auch beim Starten einer Kameraübertragung.

Mögliche Ursachen

Falsche oder fehlende announcedIp-Einstellung (mediasoup, BBB 2.5+): Der Medienserver bewirbt eine private IP-Adresse (z. B. 10.x.x.x oder 172.x.x.x) im SDP-Angebot, statt der öffentlich erreichbaren IP. Clients im Internet können diese Adresse nicht erreichen, sodass alle Verbindungsprüfungen sofort scheitern.
coturn-Bind-Fehler bei Cloud-NAT (errno=99): Auf Cloud-Instanzen (AWS, GCP, Hetzner) hinter 1:1-NAT schlägt der Versuch fehl, coturn direkt an die öffentliche IP zu binden. Das Ergebnis ist ein defektes TURN-Relay mit nicht erreichbaren Kandidaten.
Firefox-Inkompatibilität mit ICE-Lite: Sowohl mediasoup als auch FreeSWITCH implementieren ICE-Lite (passive Rolle). Firefox hat bekannte Probleme mit ICE-Lite-Gegenstellen und kann dabei den ICE-Rollenabgleich oder den Austausch der Binding Requests fehlerhaft durchführen – alle Kandidatenpaare schlagen fehl.
UDP-Ports durch Firewall gesperrt: Eingehende UDP-Pakete zu den BBB-Medienports (16384–32768 bei BBB ≤ 2.6, 32768–65535 ab BBB 2.7) werden vom Server oder von einer Cloud-Sicherheitsgruppe blockiert. Ebenso kann eine restriktive Unternehmens-Firewall ausgehende UDP-Verbindungen vom Client sperren.
Symmetrisches NAT auf Client-Seite: Hinter einem symmetrischen NAT ändert sich der Port des Clients pro Zieladresse. Der direkte UDP-Pfad zum Server schlägt fehl; ohne funktionierendes TURN-Relay werden alle Kandidatenpaare aufgebraucht.
ICE-TCP-Probleme in Kurento (BBB ≤ 2.4): Bei aktiviertem iceTcp=1 versucht Kurento TCP-basierte ICE-Kandidaten. In eingeschränkten Netzwerken scheitert dies, ohne dass ein sauberer Fallback auf UDP stattfindet.

Lösungen

Für Teilnehmer

Wechseln Sie den Browser: Verwenden Sie Google Chrome oder Microsoft Edge statt Firefox, da Firefox bekannte Inkompatibilitäten mit BBB’s ICE-Implementierung hat.
Prüfen Sie Ihre Netzwerkverbindung: Wechseln Sie von WLAN auf eine kabelgebundene Verbindung oder testen Sie in einem anderen Netzwerk (z. B. Mobilfunk-Hotspot), um zu prüfen, ob eine Unternehmens-Firewall UDP blockiert.
VPN deaktivieren: Trennen Sie eine aktive VPN-Verbindung testweise, da diese häufig UDP-Datenverkehr einschränkt oder zu symmetrischem NAT führt.
Seite neu laden und erneut versuchen: Manchmal hilft ein vollständiger Seitenneuladevorgang (Strg+Umschalt+R), um eine unterbrochene Verbindungsinitialisierung zurückzusetzen.

Für Administratoren

announcedIp für mediasoup korrekt setzen (BBB 2.5+): Der häufigste Grund für Fehler 2022 ist eine falsch konfigurierte öffentliche IP. Führen Sie folgende Befehle auf dem BBB-Server aus:

PUBLIC_IP=$(curl -s https://api.ipify.org)

yq w -i /etc/bigbluebutton/bbb-webrtc-sfu/production.yml \
    mediasoup.webrtc.listenIps[0].ip "0.0.0.0"
yq w -i /etc/bigbluebutton/bbb-webrtc-sfu/production.yml \
    mediasoup.webrtc.listenIps[0].announcedIp "$PUBLIC_IP"
yq w -i /etc/bigbluebutton/bbb-webrtc-sfu/production.yml \
    mediasoup.plainRtp.listenIp.ip "0.0.0.0"
yq w -i /etc/bigbluebutton/bbb-webrtc-sfu/production.yml \
    mediasoup.plainRtp.listenIp.announcedIp "$PUBLIC_IP"

sudo bbb-conf --restart

coturn bei Cloud-NAT korrekt konfigurieren: Auf Cloud-Instanzen hinter 1:1-NAT darf coturn nicht direkt an die öffentliche IP gebunden werden. Passen Sie /etc/turnserver.conf wie folgt an:

# /etc/turnserver.conf
listening-ip=0.0.0.0              # an alle internen Interfaces binden
external-ip=ÖFFENTLICHE_IP/PRIVATE_IP  # z.B. 1.2.3.4/10.0.0.5

# NICHT verwenden auf Cloud-Instanzen (verursacht errno=99):
# listening-ip=ÖFFENTLICHE_IP

sudo systemctl restart coturn

TURN-Relay für Firefox erzwingen: Um die Firefox/ICE-Lite-Inkompatibilität zu umgehen, kann für Firefox-Clients automatisch ein TURN-Relay erzwungen werden. Bearbeiten Sie /etc/bigbluebutton/bbb-html5.yml:

public:
  media:
    forceRelayOnFirefox: true

sudo systemctl restart bbb-html5

UDP-Ports in der Firewall freigeben:

# BBB 2.7+ (mediasoup):
sudo ufw allow 32768:65535/udp

# BBB ≤ 2.6:
sudo ufw allow 16384:32768/udp

# Für coturn:
sudo ufw allow 3478/udp
sudo ufw allow 443/udp
sudo ufw allow 443/tcp

Prüfen Sie zusätzlich die Sicherheitsgruppen-Regeln in Ihrer Cloud-Konsole (AWS Security Groups, GCP Firewall Rules usw.) und stellen Sie sicher, dass die o. g. UDP-Portbereiche eingehend erlaubt sind.

ICE-TCP in Kurento deaktivieren (BBB ≤ 2.4):

sudo nano /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini
# Auskommentierung entfernen und setzen:
# iceTcp=0

sudo systemctl restart kurento-media-server bbb-webrtc-sfu

TURN-Server einrichten: Wenn Clients hinter symmetrischem NAT oder restriktiven Unternehmensfirewalls arbeiten, ist ein korrekt konfigurierter TURN-Relay die einzige zuverlässige Lösung. Prüfen Sie nach der Einrichtung die Konfiguration mit sudo bbb-conf --check.

Weitere Informationen

Abgrenzung zu verwandten Fehlercodes: Fehler 2021 tritt eine Phase früher auf – bereits während der ICE-Kandidatenermittlung auf dem Server (Gathering-Fehler). Fehler 2022 bedeutet dagegen, dass Kandidaten vorhanden sind, aber keine einzige Kandidatenpaar-Verbindungsprüfung erfolgreich war. Fehler 1012 ist ein WebSocket-Verbindungsfehler auf Signalebene und tritt vor dem ICE-Verfahren auf – wenn Sie 1012 und 2022 gleichzeitig sehen, liegt wahrscheinlich ein allgemeines Netzwerkproblem vor.

Versionshinweise: In BBB 2.5+ ist eine falsch konfigurierte announcedIp bei weitem die häufigste Ursache für Fehler 2022. Ab BBB 2.6 wird coturn standardmäßig durch bbb-install.sh installiert; prüfen Sie /etc/bigbluebutton/turn-stun-servers.xml, um sicherzustellen, dass er korrekt eingetragen ist. Ab BBB 2.7 hat sich der UDP-Portbereich auf 32768–65535 geändert – Firewall-Regeln müssen entsprechend angepasst werden.