Saltar al contenido principal
Algunas redes corporativas y empresariales realizan interceptación TLS (“inspección SSL”) sobre el tráfico HTTPS saliente (habitualmente mediante Zscaler u otras puertas de enlace de seguridad similares). Windsurf Editor debe establecer conexiones TLS salientes con servicios externos (para el inicio de sesión y las funciones basadas en la nube). Si el tráfico inspeccionado se vuelve a firmar con una CA de inspección de la organización en la que tu máquina o entorno de ejecución no confía (o la cadena está incompleta), Windsurf puede no lograr conectarse y mostrar errores de SSL/certificado o de negociación. En particular, puede ser necesario solucionar problemas de inspección SSL/TLS si:
  • Ves “Failed to connect” u otros errores de red similares
  • El editor o el panel de Cascade muestran una pantalla en blanco y nunca llegan a cargar
  • Cascade u otras funciones basadas en la nube no pueden cargarse ni conectarse
  • Los flujos de inicio de sesión o activación fallan inesperadamente
  • Las funciones se ejecutan correctamente en una red doméstica/hotspot pero fallan en la red corporativa
  • Ves errores de certificado o de negociación (handshake) TLS en los logs o en las devtools
Si también tienes problemas relacionados con el proxy, consulta Proxy Configuration.

​
1. Verifica si tu red utiliza inspección SSL

Antes de cambiar nada en el editor, pregunta a tu equipo de TI / seguridad / redes:
  • ¿Realizamos interceptación TLS / inspección SSL en el tráfico HTTPS saliente?
  • ¿Está habilitada la inspección SSL para las estaciones de trabajo de desarrollo y las herramientas para desarrolladores (no solo los navegadores)?
  • ¿Qué cadena de CA raíz / CA intermedia se utiliza para firmar el tráfico inspeccionado?
  • ¿Se ha desplegado esa cadena de CA en los endpoints y está confiada por las aplicaciones y entornos de ejecución (runtimes) usados para el desarrollo?
Si tu organización no utiliza inspección SSL, normalmente no necesitas seguir esta guía. Si tu organización sí utiliza inspección SSL, continúa a continuación.

​
2. Capturar el error subyacente en Windsurf (Developer Tools → Console)

Windsurf Editor (basado en VS Code) expone Developer Tools que pueden mostrar los errores reales de TLS/certificados.
  1. Abre Help → Dev Tools / Developer Tools
  2. Selecciona la pestaña Console
  3. Busca errores en rojo
  4. Expande cada entrada de error para ver todos los detalles (campos de error anidados / trazas de pila)
Los patrones de error comunes incluyen: Fallos de confianza en el certificado (CA no de confianza):
  • certificate signed by unknown authority
  • unable to verify the first certificate
  • self signed certificate in certificate chain
  • UNABLE_TO_VERIFY_LEAF_SIGNATURE
Fallos al construir la cadena (intermedio faltante):
  • unable to get local issuer certificate
  • unable to get issuer certificate
Fallos de negociación TLS:
  • handshake_failure
  • wrong version number
  • protocol negotiation failed
  • ERR_SSL_PROTOCOL_ERROR
Si puedes proporcionar el texto expandido del error de la consola al equipo de TI/seguridad, normalmente se reduce de forma significativa el tiempo de resolución.

​
3. Qué causa esto en entornos con inspección SSL

Cuando la inspección SSL está habilitada, el gateway termina y vuelve a establecer las conexiones TLS. Al cliente se le presenta un certificado de servidor sintético firmado por una CA de inspección de la empresa (certificados de CA raíz y, a veces, de CA intermedia). Los errores de conectividad de Windsurf suelen producirse cuando:
  • La CA raíz de inspección de la empresa no es de confianza en el endpoint y/o
  • La cadena del certificado de inspección está incompleta (falta la CA intermedia) y/o
  • El IDE/runtime usa un almacén de confianza distinto del del sistema operativo que no incluye la cadena de la CA de inspección de la empresa y/o
  • La política de la empresa impone restricciones TLS que impiden la negociación (versión/cifrados mínimos de TLS, bloqueo de tráfico que no se puede descifrar, etc.)
En general, esto es un problema de configuración de certificados/confianza/políticas de la empresa, no un problema específico de implementación de Windsurf.

​
4. Trabaja con tu equipo de TI / seguridad para resolverlo

Dado que la inspección SSL y la implementación de certificados están controladas por tu organización, normalmente será necesario que el equipo de TI/seguridad realice cambios.

​
A) Validar la política de inspección SSL para el tráfico de Windsurf

Pida al equipo de TI y seguridad que confirme:
  • Si la inspección SSL se aplica al tráfico HTTPS saliente relacionado con Windsurf
  • Si se producen bloqueos o denegaciones debido a problemas en la validación de certificados, motivos de política o restricciones en la negociación TLS

​
B) Asegúrate de que la cadena de la CA de inspección de la empresa esté correctamente instalada y sea de confianza

Pide al equipo de TI/seguridad que:
  • Implemente la Root CA de inspección SSL de la empresa en los equipos de los desarrolladores
  • Se asegure de que cualquier certificado de CA intermedia requerido esté presente y de que la cadena sea correcta
  • Valide la confianza utilizando el mismo almacén de confianza que usa el IDE/entorno de ejecución (almacén del sistema operativo vs almacén específico del entorno de ejecución)

​
C) Configurar una excepción de inspección SSL con ámbito limitado (alternativa)

Si no es posible alinear la confianza, pida al equipo de TI/seguridad que:
  • Cree una excepción de inspección SSL para los endpoints de los servicios de Windsurf que sean necesarios (según el proceso de lista de permitidos/requisitos de red de su organización)
  • Mantenga la excepción con un ámbito reducido y alineada con su política de seguridad

​
5. Qué enviar a TI / seguridad (copiar/pegar)

Problema: Windsurf Editor no logra conectarse en la red corporativa; probablemente se deba a un problema de confianza o de cadena del certificado de inspección SSL/interceptación TLS. Evidencia: Ayuda → Herramientas para desarrolladores → Consola muestra errores de TLS/certificados o de negociación (handshake) (hay errores de consola en rojo expandidos disponibles). Solicitud:
  1. Confirmar si la inspección SSL está habilitada para el tráfico HTTPS saliente relacionado con Windsurf.
  2. Confirmar que la CA raíz de inspección SSL de la empresa y cualquier certificado intermedio estén desplegados y sean de confianza en este endpoint (y en cualquier almacén de confianza específico del runtime usado por el IDE).
  3. Si la alineación de confianza no es factible, configurar una excepción de inspección SSL limitada para los endpoints de servicio de Windsurf requeridos.
Incluir:
  • Marca(s) de tiempo del fallo
  • Versión del SO
  • Si Zscaler Client Connector (u otro agente similar) está instalado/habilitado
  • Texto expandido del error de consola desde Herramientas para desarrolladores → Consola
  • Si funciona en un hotspot/red doméstica pero falla en la red corporativa

​
6. Cuándo usar cada opción

Usa las correcciones de implementación/confianza de certificados si:
  • Los errores indican “unknown authority”, “unable to verify”, “issuer not found” o faltan certificados intermedios
  • Quieres la solución más duradera manteniendo habilitada la inspección SSL
Usa una excepción de inspección SSL acotada si:
  • El IDE o el runtime no pueden, en la práctica, consumir la cadena de AC de la empresa
  • La alineación del almacén de confianza no es confiable en tu entorno
  • El equipo de TI/seguridad confirma que la inspección está causando fallos y aprueba una excepción específica
Si no estás seguro de cuál aplica, tu equipo de TI/seguridad es la fuente de referencia: pueden confirmar si la inspección SSL está habilitada, qué cadena de AC se utiliza, cómo se gestionan los endpoints y si las reglas de excepción son apropiadas.