> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Probleme mit TLS-/SSL-Inspektion in Windsurf

> Konfiguration von Unternehmensumgebungen, in denen SSL-Inspektion (z. B. Zscaler) zu TLS-Zertifikatsvalidierungs- oder Protokollaushandlungsfehlern führt. Enthält Hinweise zum Erfassen von Konsolenfehlern und dazu, was Sie bei der IT-/Sicherheitsabteilung anfragen sollten.

Einige Unternehmens- und Enterprise-Netzwerke führen TLS-Abfangmaßnahmen („SSL-Inspektion“) für ausgehenden HTTPS-Datenverkehr durch (häufig über Zscaler oder ähnliche Sicherheits-Gateways). Windsurf Editor muss ausgehende TLS-Verbindungen zu externen Diensten herstellen (für Anmeldung und cloudgestützte Funktionen). Wenn inspizierter Datenverkehr von einer Enterprise-Inspektions-CA neu signiert wird, der Ihr Rechner bzw. Ihre Laufzeitumgebung nicht vertraut (oder die Zertifikatskette unvollständig ist), kann Windsurf möglicherweise keine Verbindung herstellen und zeigt SSL-/Zertifikats- oder Protokollaushandlungsfehler an.

Insbesondere kann eine Fehlerbehebung der SSL/TLS-Inspektion erforderlich sein, wenn:

* Sie „Failed to connect“ oder ähnliche Netzwerkfehler sehen

* Der Editor oder das Cascade-Panel einen leeren Bildschirm zeigt und nie lädt

* Cascade oder andere cloudgestützte Funktionen nicht laden oder keine Verbindung herstellen können

* Anmelde- oder Aktivierungsabläufe unerwartet fehlschlagen

* Funktionen über einen Hotspot oder ein Heimnetzwerk funktionieren, aber im Unternehmensnetzwerk fehlschlagen

* Sie Zertifikats- oder TLS-Handshake-Fehler in Logs/DevTools sehen

<Note>
  Wenn Sie auch Proxy-bezogene Probleme haben, siehe [Proxy Configuration](/de/troubleshooting/windsurf-proxy-configuration).
</Note>

***

<div id="1-check-whether-your-network-uses-ssl-inspection">
  ## 1. Prüfen Sie, ob Ihr Netzwerk SSL-Inspection verwendet
</div>

Bevor Sie etwas im Editor ändern, fragen Sie Ihr IT-/Security-/Netzwerkteam:

* Führen wir TLS-Interception / SSL-Inspection für ausgehenden HTTPS‑Traffic durch?

* Ist SSL-Inspection für Entwicklerarbeitsstationen und Entwicklertools aktiviert (nicht nur für Browser)?

* Welche Root-CA-/Intermediate-CA-Kette wird verwendet, um inspizierten Traffic zu signieren?

* Ist diese CA-Kette auf Endgeräten ausgerollt und wird sie von den für die Entwicklung genutzten Anwendungen/Runtimes als vertrauenswürdig eingestuft?

Wenn Ihre Organisation keine SSL-Inspection verwendet, müssen Sie dieser Anleitung in der Regel nicht folgen. Wenn Ihre Organisation SSL-Inspection verwendet, fahren Sie unten fort.

***

<div id="2-capture-the-underlying-error-in-windsurf-developer-tools-console">
  ## 2. Den zugrundeliegenden Fehler in Windsurf erfassen (Developer Tools → Console)
</div>

Windsurf Editor (VS Code–basiert) stellt Developer Tools bereit, die die tatsächlichen TLS-/Zertifikatsfehler anzeigen können.

1. Öffne **Help → Dev Tools** / **Developer Tools**

2. Wähle den Reiter **Console**

3. Suche nach **roten Fehlermeldungen**

4. Klappe jeden Fehlereintrag auf, um alle Details zu sehen (verschachtelte Fehlerfelder / Stack-Traces)

Häufige Fehlermuster sind:

**Zertifikatsvertrauensfehler (nicht vertrauenswürdige CA):**

* `certificate signed by unknown authority`

* `unable to verify the first certificate`

* `self signed certificate in certificate chain`

* `UNABLE_TO_VERIFY_LEAF_SIGNATURE`

**Fehler beim Aufbau der Zertifikatskette (fehlende Zwischenzertifikate):**

* `unable to get local issuer certificate`

* `unable to get issuer certificate`

**TLS-Aushandlungsfehler:**

* `handshake_failure`

* `wrong version number`

* `protocol negotiation failed`

* `ERR_SSL_PROTOCOL_ERROR`

Wenn du deiner IT-/Security-Abteilung den aufgeklappten Fehlertext aus der Konsole bereitstellen kannst, verkürzt das die Lösungszeit in der Regel erheblich.

***

<div id="3-what-causes-this-in-ssl-inspected-environments">
  ## 3. Ursachen in SSL-inspektierten Umgebungen
</div>

Wenn SSL-Inspektion aktiviert ist, beendet das Gateway TLS-Verbindungen und baut sie neu auf. Dem Client wird ein synthetisches Serverzertifikat präsentiert, das von einer unternehmensinternen Inspektions-CA (Root-CA- und manchmal Intermediate-CA-Zertifikate) signiert ist.

Windsurf-Konnektivitätsfehler treten typischerweise auf, wenn:

* Der unternehmensinternen Inspektions-**Root-CA nicht vertraut** wird (nicht als vertrauenswürdig auf dem Endpunkt installiert ist) und/oder

* Die **Kette des Inspektionszertifikats unvollständig** ist (fehlende Intermediate-CA) und/oder

* Das IDE bzw. die Runtime einen **eigenen, nicht vom Betriebssystem verwalteten Trust Store** verwendet, der die Kette der unternehmensinternen Inspektions-CA nicht enthält, und/oder

* Unternehmensrichtlinien TLS-Einschränkungen erzwingen, die die Aushandlung verhindern (minimale TLS-Version/Cipher-Suites, Blockieren von Datenverkehr, der nicht entschlüsselt werden kann, usw.)

Dies ist im Allgemeinen ein Problem der Zertifikats-, Vertrauens- und Richtlinienkonfiguration im Unternehmen, kein Windsurf-spezifisches Implementierungsproblem.

***

<div id="4-work-with-your-it-security-team-to-resolve">
  ## 4. Arbeiten Sie mit Ihrem IT-/Sicherheitsteam an der Lösung
</div>

Da SSL-Inspektion und Zertifikatsbereitstellung von Ihrer Organisation gesteuert werden, sind zur Behebung des Problems in der Regel Änderungen durch Ihr IT-/Sicherheitsteam erforderlich.

<div id="a-validate-ssl-inspection-policy-for-windsurf-traffic">
  ### A) SSL-Inspektionsrichtlinie für Windsurf-Datenverkehr prüfen
</div>

Bitten Sie Ihr IT-/Security-Team, zu bestätigen:

* Ob SSL-Inspektion auf ausgehenden HTTPS-Datenverkehr im Zusammenhang mit Windsurf angewendet wird

* Ob Blockierungen/Verweigerungen aufgrund von Zertifikatsvalidierung, Richtlinienvorgaben oder Einschränkungen bei der TLS-Aushandlung auftreten

<div id="b-ensure-the-enterprise-inspection-ca-chain-is-correctly-deployed-and-trusted">
  ### B) Sicherstellen, dass die unternehmensweite SSL-Inspektions-CA-Kette korrekt bereitgestellt und als vertrauenswürdig konfiguriert ist
</div>

Bitten Sie Ihr IT-/Security-Team, Folgendes zu tun:

* Die unternehmensweite SSL-Inspektions-**Root CA** auf den Entwicklerendgeräten zu installieren

* Sicherzustellen, dass alle erforderlichen **Intermediate-CA-Zertifikate** vorhanden sind und die Kette korrekt ist

* Die Vertrauenskette mit demselben Trust Store zu überprüfen, den das IDE bzw. die Laufzeitumgebung verwendet (Trust Store des Betriebssystems vs. laufzeitspezifischer Trust Store)

<div id="c-configure-a-scoped-ssl-inspection-bypass-fallback">
  ### C) Einen gezielten SSL-Inspection-Bypass konfigurieren (Fallback)
</div>

Wenn eine Vertrauensangleichung nicht möglich ist, bitte dein IT-/Sicherheitsteam:

* Eine Ausnahme von der SSL-Inspection für die erforderlichen Windsurf-Service-Endpunkte einrichten (gemäß dem Allowlist-/Netzwerkfreigabeprozess deiner Organisation)

* Den Bypass möglichst eng begrenzen und an eurer Sicherheitsrichtlinie ausrichten

***

<div id="5-what-to-send-to-it-security-copypaste">
  ## 5. Was an IT-/Security-Team schicken (Copy & Paste)
</div>

**Problem:** Windsurf Editor kann im Firmennetzwerk keine Verbindung herstellen; wahrscheinlich ein Problem mit dem Vertrauen in das SSL-Inspection-/TLS-Interception-Zertifikat oder in die Zertifikatskette.

**Nachweise:** Hilfe → Developer Tools → Console zeigt TLS-/Zertifikats- oder Handshake-Fehler (detaillierte rote Konsolenfehlermeldungen verfügbar).

**Anfrage:**

1. Bitte bestätigen, ob SSL-Inspection für ausgehenden HTTPS-Traffic im Zusammenhang mit Windsurf aktiviert ist.

2. Bitte bestätigen, dass die Enterprise-SSL-Inspection-Root-CA und alle Intermediate-Zertifikate auf diesem Endpunkt (und in jedem laufzeitspezifischen Truststore, der von der IDE verwendet wird) bereitgestellt und als vertrauenswürdig eingestuft sind.

3. Falls eine Angleichung der Vertrauensstellungen nicht möglich ist, bitte eine gezielte Ausnahme (Bypass) für die SSL-Inspection der benötigten Windsurf-Service-Endpunkte konfigurieren.

**Beifügen:**

* Zeitstempel der Fehlermeldung(en)

* Betriebssystemversion

* Ob Zscaler Client Connector (oder ein ähnlicher Agent) installiert/aktiviert ist

* Erweiterter Konsolenfehlertest aus Developer Tools → Console

* Ob es in einem Hotspot-/Heimnetzwerk funktioniert, aber im Firmennetzwerk fehlschlägt

***

<div id="6-when-to-use-which-option">
  ## 6. Wann welche Option verwenden
</div>

Verwenden Sie Maßnahmen zur Bereitstellung/Vertrauensstellung von Zertifikaten, wenn:

* Fehlermeldungen auf „unknown authority“, „unable to verify“, „issuer not found“ oder fehlende Zwischenzertifikate hinweisen

* Sie die dauerhafteste Lösung möchten, während SSL-Inspection aktiviert bleibt

Verwenden Sie einen gezielt eingeschränkten SSL-Inspection-Bypass, wenn:

* das IDE bzw. die Runtime die Enterprise-CA-Kette praktisch nicht verwenden kann

* die Angleichung der Truststores in Ihrer Umgebung unzuverlässig ist

* Ihr IT-/Security-Team bestätigt, dass die SSL-Inspection Fehler verursacht, und eine gezielte Ausnahme genehmigt

Wenn Sie nicht sicher sind, was zutrifft, ist Ihr IT-/Security-Team die maßgebliche Instanz – es kann bestätigen, ob SSL-Inspection aktiviert ist, welche CA-Kette verwendet wird, wie Endpunkte verwaltet werden und ob Bypass-Regeln angemessen sind.