Solución de problemas

"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):

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:

Revisar los registros:

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

No se puede iniciar sesión en Verdent for VS Code

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

Solución:

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 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 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

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:

Mensajes de error relacionados con imágenes

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

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:

# 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)

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:

# 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

La búsqueda no devuelve resultados

Problema: grep_file o glob no encuentran los archivos esperados

Comprueba la sintaxis del patrón:

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

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

Comprueba las exclusiones:

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

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

# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)

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

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

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:

# 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)

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

Limitaciones de archivos binarios

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

Solución alternativa:

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

Manejo de archivos grandes

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

Solución alternativa:

# 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")

Diferencias de comandos entre plataformas

Problema: los comandos bash difieren entre Windows y Unix

Solución alternativa:

# 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.