---
title: "Solución de problemas"
description: "Problemas comunes, diagnósticos y soluciones"
---

### Lo que aprenderás

Procedimientos comunes de solución de problemas, pasos de diagnóstico y soluciones alternativas para problemas conocidos de Verdent for VS Code.

<Info>
  La solución de problemas detallada para los principales problemas reportados por los usuarios se está recopilando a partir de datos de soporte. Esta página proporciona procedimientos de diagnóstico generales. Contacta a [support@verdent.ai](mailto:support@verdent.ai) para problemas específicos que no se cubran aquí.
</Info>

---

## Diagnósticos rápidos

<Tabs>
  <Tab title="Errores de servicio (los más comunes)">
    ### "Service is experiencing high traffic. Please try again later!"

    **Este es el error número 1 más común** que encuentran los usuarios. Indica que el servicio de Verdent está temporalmente sobrecargado.

    **Cuándo ocurre:**

    - Durante horas de uso máximo
    - Cuando los servicios de backend están bajo mucha carga
    - Degradación temporal del servicio

    **Pasos de recuperación (en orden):**

    <Steps>
      <Step title="Revertir el mensaje" stepNumber={1}>
        Si el error persiste, revierte el mensaje más reciente:

        - Selecciona el botón de revertir/deshacer en la interfaz de chat
        - Vuelve a enviar tu solicitud después de una breve espera
      </Step>
      <Step title="Iniciar una nueva sesión" stepNumber={2}>
        Si los errores continúan, inicia una sesión nueva:

        - Selecciona el botón "+" (Nueva sesión) en la barra superior
        - Esto borra el contexto y las aprobaciones de herramientas
        - Vuelve a enviar tu solicitud en la sesión limpia
      </Step>
      <Step title="Esperar y reintentar" stepNumber={3}>
        Espera entre 30 y 60 segundos e intenta tu solicitud de nuevo. La mayoría de los problemas de servicio se resuelven rápidamente.
      </Step>
    </Steps>
    <Warning>
      Si el problema persiste por más de 5 a 10 minutos en varias sesiones, consulta la [página de estado de Verdent](https://verdent.ai/status) o contacta a [support@verdent.ai](mailto:support@verdent.ai).
    </Warning>
  </Tab>
  <Tab title="Instalación y configuración">
    ### Problemas de instalación y configuración

    **Requisitos del sistema:**

    - **Versión de VS Code:** 1.90.0 o posterior (requerida)
    - **Conexión a internet:** se requiere una conexión activa
    - **Suscripción:** suscripción activa de Verdent

    **Lista de verificación de diagnóstico básico:**

    1. **Verifica la versión de VS Code:** Help → About (debe ser 1.90.0+)
    2. **Comprueba la conexión a internet:** Verdent requiere una conexión activa
    3. **Verifica la suscripción:** asegúrate de que la suscripción de Verdent esté activa
    4. **Reinicia VS Code:** después de la instalación o de cambios de configuración
    5. **Comprueba el estado de la extensión:** View → Extensions → Verdent (debe mostrar "Enabled")

    **Procedimiento de reinstalación limpia:**

    <Steps>
      <Step title="Desinstalar Verdent">
        View → Extensions → Verdent → Uninstall
      </Step>
      <Step title="Reiniciar VS Code">
        Cierra y vuelve a abrir VS Code por completo
      </Step>
      <Step title="Reinstalar Verdent">
        View → Extensions → Busca "Verdent" → Install
      </Step>
    </Steps>
    **Revisar los registros:**

    - Abre el panel Output: View → Output
    - Selecciona "Verdent" en el menú desplegable
    - Busca mensajes de error o trazas de pila

    <Info>
      La mayoría de los problemas de instalación se resuelven con una simple recarga de VS Code o una reinstalación limpia. Si los problemas persisten, revisa los registros y contacta a soporte con los detalles del registro.
    </Info>
  </Tab>
  <Tab title="Autenticación y cuenta">
    ### No se puede iniciar sesión en Verdent for VS Code

    **Causa más común:** problema de configuración del proxy

    **Solución:**

    <Steps>
      <Step title="Abrir la configuración de VS Code">
        Presiona `Cmd+,` (macOS) o `Ctrl+,` (Windows/Linux)
      </Step>
      <Step title="Buscar la configuración del proxy">
        Busca "useProxy" o "verdent.enableProxy" en la barra de búsqueda de configuración
      </Step>
      <Step title="Cambiar el estado del proxy">
        Activa/desactiva la configuración del proxy (lo opuesto al estado actual)
      </Step>
      <Step title="Reintentar el inicio de sesión">
        Intenta iniciar sesión en Verdent de nuevo
      </Step>
    </Steps>
    <Info>
      Si estás detrás de un firewall corporativo, es posible que debas habilitar la configuración del proxy. Si estás en una red doméstica, intenta deshabilitarla.
    </Info>
    ---

    ### No se recibieron los créditos de prueba gratuita

    **Error:** no se recibieron los créditos de prueba gratuita o se denegó el acceso a la prueba gratuita

    **Razón:** se detectó una violación de los términos del servicio durante el registro

    **Resolución:** contacta a [support@verdent.ai](mailto:support@verdent.ai) para obtener ayuda con tu acceso a la prueba gratuita. El equipo de soporte revisará tu cuenta y te ayudará a resolver el problema.

    ---

    ### Error de registro

    **Error:** el registro de la cuenta fue rechazado o restringido

    **Razón:** el registro violó los términos del servicio de Verdent, lo que resultó en una restricción de acceso

    **Resolución:** contacta a [support@verdent.ai](mailto:support@verdent.ai) para obtener ayuda. El equipo de soporte puede revisar tu registro y orientarte sobre cómo resolver el problema.

    ---

    ### Modelos faltantes (Claude, GPT, Gemini)

    **Problema:** no se encuentran los modelos Claude, GPT o Gemini en la selección de modelos

    **Razón:** restricciones basadas en la ubicación impuestas por los proveedores de modelos

    **Explicación:** algunos proveedores de modelos de IA tienen restricciones regionales que impiden que ciertos modelos estén disponibles en ubicaciones geográficas específicas. Cuando esto ocurre:

    - Los modelos restringidos no aparecerán en tu menú de selección de modelos
    - Aún puedes usar todos los demás modelos disponibles sin interrupción
    - No hay impacto en tu suscripción ni en tus créditos

    **Consulta los modelos disponibles:** visita https://www.verdent.ai/regions para ver qué modelos están disponibles en tu región

    <Note>
      Las restricciones regionales las establecen los proveedores de modelos de IA (Anthropic, OpenAI, Google), no Verdent. Verdent no puede anular estas restricciones.
    </Note>
  </Tab>
  <Tab title="Rendimiento">
    ### Problemas de rendimiento

    **Síntomas:**

    - Tiempos de respuesta lentos
    - Errores de ventana de contexto llena
    - Tiempos de espera agotados en la ejecución de herramientas

    **Causas comunes y soluciones:**

    | Problema             | Causa                        | Solución                                                              |
    | ----------------- | ---------------------------- | --------------------------------------------------------------------- |
    | Respuestas lentas    | Lectura de archivos grandes       | Usa rangos de líneas: `file_read("file.js", start_line=100, max_lines=50)` |
    | Contexto lleno      | Historial de conversación largo    | Delega en subagentes o inicia una nueva conversación                       |
    | Tiempos de espera de herramientas     | Comandos bash de larga ejecución   | Establece un tiempo de espera explícito o divide en comandos más pequeños                   |
    | Uso elevado de memoria | Demasiadas operaciones en paralelo | Limita las ejecuciones de herramientas concurrentes                                      |

    <Tip>
      Delega las tareas exploratorias al subagente @Explorer para preservar el contexto principal.
    </Tip>
  </Tab>
  <Tab title="Errores de imagen">
    ### Mensajes de error relacionados con imágenes

    **Referencia rápida para errores comunes de procesamiento de imágenes:**

    | Mensaje de error                  | Causa                                                                    | Solución                                                      |
    | ------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
    | **Unsupported Image Type**     | Solo se admiten imágenes JPEG, PNG, GIF o WebP                        | Revierte y cambia el tipo de imagen a un formato compatible     |
    | **Image Dimensions Too Large** | El ancho o el alto de la imagen no puede superar los 8000 píxeles                          | Revierte y ajusta las dimensiones de la imagen a 8000×8000 o menos |
    | **Input Too Long**             | La entrada supera la longitud máxima permitida por el modelo                     | Simplifica tu entrada o reduce el tamaño de la imagen                       |
    | **File Too Large**             | El tamaño de la imagen no puede superar los 5 MB                                            | Revierte y envía una imagen comprimida (máx. 5 MB)              |
    | **Unreadable Image**           | No se pudo procesar la imagen; el archivo puede estar dañado o tener un formato no compatible | Revierte y reemplaza la imagen con un archivo válido             |
  </Tab>
</Tabs>

---

## Problemas específicos de herramientas

<Tabs>
  <Tab title="Fallos de file_edit">
    ### Fallos de file_edit

    **Error:** "Failed to find exact match"

    **Causas:**

    - El texto cambió desde la última operación file_read
    - Diferencias de espacios en blanco (tabulaciones vs espacios)
    - La cadena no es única en el archivo

    **Soluciones:**

    ```bash
    # 1. Read file again to get current state
    file_read("file.js")

    # 2. Use larger context string for uniqueness
    file_edit("file.js",
      old_string="function foo() {\n  return 42;\n}",
      new_string="...")

    # 3. For multiple identical strings, use replace_all
    file_edit("file.js", old_string="TODO", new_string="DONE", replace_all=true)
    ```

    <Warning>
      Lee siempre el archivo justo antes de editarlo para asegurarte de tener el estado actual.
    </Warning>
  </Tab>
  <Tab title="Fallos de bash">
    ### Fallos de comandos bash

    **Error:** tiempo de espera del comando agotado o fallo de ejecución

    **Tiempo de espera máximo:** 120 segundos (2 minutos, límite estricto)

    **Solución:** divide los comandos largos en operaciones más pequeñas:

    ```bash
    # Instead of one long command, break into steps
    bash("step1")  # Completes in < 2min
    bash("step2")  # Completes in < 2min
    ```

    **Comando no encontrado:**

    - Comprueba si el comando existe: `bash("which command-name")`
    - Asegúrate de la ruta correcta o activa primero el entorno
    - Usa rutas completas para los ejecutables

    **Errores de permisos:**

    - Los comandos se ejecutan con los permisos del usuario
    - Usa `sudo` solo si es necesario y en Manual Accept Mode
    - Comprueba los permisos de archivos/directorios
  </Tab>
  <Tab title="Problemas de búsqueda">
    ### La búsqueda no devuelve resultados

    **Problema:** grep_file o glob no encuentran los archivos esperados

    **Comprueba la sintaxis del patrón:**

    ```bash
    # Wrong
    grep_file("*.ts")  # Missing ** for recursive

    # Correct
    grep_file("**/*.ts")  # Recursive search
    ```

    **Comprueba las exclusiones:**

    ```bash
    # Ensure not accidentally excluding target files
    glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])
    ```

    **Distinción de mayúsculas y minúsculas:**

    ```bash
    # Use case-insensitive search if needed
    grep_content("pattern", case_insensitive=true)
    ```
  </Tab>
</Tabs>

---

## Problemas de subagentes y configuración

<Tabs>
  <Tab title="El subagente no se invoca">
    ### El subagente no se invoca

    **Problema:** un subagente personalizado no se activa automáticamente

    **Lista de verificación:**

    - Ubicación del archivo: `~/.verdent/subagents/[name].md`
    - Frontmatter YAML válido con `name` y `description`
    - La política de invocación coincide con el uso (strict requiere una mención con @)
    - Las pautas de "Cuándo usarlo" coinciden con el patrón de la solicitud
    - No hay errores de sintaxis en el archivo markdown

    **Pruébalo manualmente:**

    ```
    @subagent-name perform task
    ```

    <Tip>
      Usa una mención explícita con @ para verificar que el subagente funciona antes de solucionar problemas de invocación automática.
    </Tip>
  </Tab>
  <Tab title="Subagentes integrados">
    ### Comportamiento de los subagentes integrados

    **Problema:** @Explorer, @Verifier o @Code-reviewer no se comportan como se espera

    **Causas comunes:**

    - La solicitud no coincide con la especialización del subagente
    - El contexto del subagente está lleno (raro)
    - El contexto de la conversación principal afecta el enrutamiento

    **Solución:**

    - Usa una mención explícita con @ para forzar un subagente específico
    - Reformula la solicitud para que coincida con la especialización del subagente
    - Inicia una nueva conversación si el contexto es un problema
  </Tab>
  <Tab title="Reglas de AGENTS.md">
    ### AGENTS.md no se aplica

    **Problema:** las reglas del proyecto no afectan el comportamiento de Verdent

    **Diagnóstico:**

    1. **Ubicación:** el archivo debe estar en el directorio raíz del proyecto
    2. **Sintaxis:** Markdown válido (busca errores de sintaxis)
    3. **Especificidad:** las reglas deben ser directivas: "Usa siempre X" y no "Intenta usar X"
    4. **Pruebas:** inicia una nueva conversación para probar una aplicación fresca

    **Comprobación de precedencia:**

    ```markdown
    # In AGENTS.md (highest priority)
    - Use 4-space indentation

    # In VERDENT.md (lower priority)
    - Use 2-space indentation

    # Result: 4-space indentation (AGENTS.md wins)
    ```
  </Tab>
  <Tab title="Conexión MCP">
    ### Fallos de conexión de MCP

    **Error:** no se puede conectar al servidor MCP

    **Pasos de diagnóstico:**

    1. **Comprueba mcp.json:** sintaxis JSON válida en `~/.verdent/mcp.json`
    2. **Servidor en ejecución:** asegúrate de que el proceso del servidor MCP esté activo
    3. **Red:** verifica la conectividad con el endpoint del servidor
    4. **Autenticación:** confirma que las credenciales sean correctas
    5. **Registros:** revisa los registros del servidor MCP para conocer los detalles del error

    **Soluciones comunes:**

    - Reinicia el servidor MCP
    - Verifica el formato de la cadena de conexión
    - Comprueba las reglas del firewall que permiten el tráfico MCP
    - Valida las claves o tokens de API
  </Tab>
</Tabs>

---

## Problemas conocidos y soluciones alternativas

<Tabs>
  <Tab title="Archivos binarios">
    ### Limitaciones de archivos binarios

    **Problema:** no se pueden editar imágenes, PDF ni binarios compilados

    **Solución alternativa:**

    ```bash
    # Use bash to call external tools
    bash("convert input.png -resize 50% output.png")
    bash("pdftotext document.pdf output.txt")
    ```

    <Info>
      Las modificaciones de archivos binarios requieren herramientas externas invocadas mediante comandos bash.
    </Info>
  </Tab>
  <Tab title="Archivos grandes">
    ### Manejo de archivos grandes

    **Problema:** los archivos de más de 10.000 líneas causan problemas de contexto

    **Solución alternativa:**

    ```bash
    # Always use line ranges for large files
    file_read("large.log", start_line=1000, max_lines=100)

    # Search first to find relevant sections
    grep_content("ERROR", glob="large.log")
    ```

    <Tip>
      Busca primero con grep_content para localizar los números de línea relevantes y luego lee solo esos rangos específicos.
    </Tip>
  </Tab>
  <Tab title="Diferencias de plataforma">
    ### Diferencias de comandos entre plataformas

    **Problema:** los comandos bash difieren entre Windows y Unix

    **Solución alternativa:**

    ```bash
    # Use cross-platform tools when possible
    bash("npm run build")  # Works everywhere

    # Or conditional execution
    bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
    ```

    **Práctica recomendada:** usa scripts de npm para la compatibilidad entre plataformas.
  </Tab>
</Tabs>

---

## Obtener ayuda adicional

### Canales de soporte

**Para problemas específicos que no se cubren aquí:**

- **Correo electrónico:** [support@verdent.ai](mailto:support@verdent.ai)
- **Discord:** [Únete a la comunidad de Verdent](https://discord.com/invite/NGjXEZcbJq) para obtener soporte en tiempo real
- **Problemas de GitHub:** reporta errores o solicita funciones

**Al reportar problemas, incluye:**

1. Versión de Verdent (desde el panel Extensions)
2. Versión de VS Code
3. Sistema operativo
4. Mensajes de error (texto exacto)
5. Pasos para reproducir
6. Comportamiento esperado vs comportamiento real

---

### Recopilación de información de diagnóstico

**Para ayudar a soporte a diagnosticar:**

```bash
# VS Code version
bash("code --version")

# System info
bash("uname -a")  # Unix
bash("systeminfo")  # Windows

# Verdent logs location
# Check VS Code Output panel → Verdent
```

---

## Consulta también

<CardGroup cols={2}>
  <Card title="Preguntas frecuentes" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    Preguntas frecuentes
  </Card>
  <Card title="Limitaciones" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    Limitaciones y restricciones conocidas
  </Card>
</CardGroup>