Solução de problemas

"Service is experiencing high traffic. Please try again later!"

Este é o erro nº 1 mais comum que os usuários encontram. Ele indica que o serviço do Verdent está temporariamente sobrecarregado.

Quando acontece:

• Durante horários de pico de uso
• Quando os serviços de back-end estão sob carga pesada
• Degradação temporária do serviço

Etapas de recuperação (em ordem):

Problemas de instalação e configuração

Requisitos do sistema:

• Versão do VS Code: 1.90.0 ou posterior (obrigatório)
• Conexão com a internet: conexão ativa necessária
• Assinatura: assinatura ativa do Verdent

Lista de verificação básica de diagnóstico:

1. Verifique a versão do VS Code: Help → About (deve ser 1.90.0+)
2. Verifique a conexão com a internet: o Verdent requer uma conexão ativa
3. Verifique a assinatura: certifique-se de que a assinatura do Verdent esteja ativa
4. Reinicie o VS Code: após a instalação ou alterações de configuração
5. Verifique o status da extensão: View → Extensions → Verdent (deve mostrar "Enabled")

Procedimento de reinstalação limpa:

Verifique os logs:

• Abra o painel Output: View → Output
• Selecione "Verdent" no menu suspenso
• Procure por mensagens de erro ou rastreamentos de pilha

Não consigo fazer login no Verdent for VS Code

Causa mais comum: problema de configuração de proxy

Solução:

Créditos de avaliação gratuita não recebidos

Erro: os créditos de avaliação gratuita não foram recebidos ou o acesso à avaliação gratuita foi negado

Motivo: violação dos termos de serviço detectada durante o cadastro

Resolução: entre em contato com support@verdent.ai para obter ajuda com seu acesso à avaliação gratuita. A equipe de suporte revisará sua conta e ajudará a resolver o problema.

Falha no cadastro

Erro: o cadastro da conta foi rejeitado ou restrito

Motivo: o cadastro violou os termos de serviço do Verdent, resultando em restrição de acesso

Resolução: entre em contato com support@verdent.ai para obter ajuda. A equipe de suporte pode revisar seu cadastro e fornecer orientação sobre como resolver o problema.

Modelos ausentes (Claude, GPT, Gemini)

Problema: não é possível encontrar os modelos Claude, GPT ou Gemini na seleção de modelos

Motivo: restrições baseadas em localização impostas pelos provedores de modelos

Explicação: alguns provedores de modelos de IA têm restrições regionais que impedem que certos modelos estejam disponíveis em localizações geográficas específicas. Quando isso acontece:

• Os modelos restritos não aparecerão no seu menu de seleção de modelos
• Você ainda pode usar todos os outros modelos disponíveis sem interrupção
• Não há impacto na sua assinatura ou créditos

Verifique os modelos disponíveis: acesse https://www.verdent.ai/regions para ver quais modelos estão disponíveis na sua região

Problemas de desempenho

Sintomas:

• Tempos de resposta lentos
• Erros de janela de contexto cheia
• Tempos limite de execução de ferramentas

Causas comuns e correções:

Mensagens de erro relacionadas a imagens

Referência rápida para erros comuns de processamento de imagens:

Falhas de file_edit

Erro: "Failed to find exact match"

Causas:

• O texto mudou desde o último file_read
• Diferenças de espaço em branco (tabs vs espaços)
• A string não é única no arquivo

Soluções:

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

Falhas de comandos bash

Erro: tempo limite do comando ou falha na execução

Tempo limite máximo: 120 segundos (2 minutos, limite rígido)

Solução: divida comandos longos em operações menores:

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

Comando não encontrado:

• Verifique se o comando existe: bash("which command-name")
• Certifique-se do caminho correto ou ative o ambiente primeiro
• Use caminhos completos para executáveis

Erros de permissão:

• Os comandos são executados com as permissões do usuário
• Use sudo apenas se necessário e no Manual Accept Mode
• Verifique as permissões de arquivo/diretório

Pesquisa não retorna resultados

Problema: grep_file ou glob não encontra os arquivos esperados

Verifique a sintaxe do padrão:

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

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

Verifique as exclusões:

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

Diferenciação entre maiúsculas e minúsculas:

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

Subagente não é invocado

Problema: o subagente personalizado não é ativado automaticamente

Lista de verificação:

• Localização do arquivo: ~/.verdent/subagents/[name].md
• Frontmatter YAML válido com name e description
• A política de invocação corresponde ao uso (strict requer @-menção)
• As diretrizes "When to use" correspondem ao padrão da solicitação
• Sem erros de sintaxe no arquivo markdown

Teste manualmente:

@subagent-name perform task

Comportamento dos subagentes integrados

Problema: @Explorer, @Verifier ou @Code-reviewer não se comportam como esperado

Causas comuns:

• A solicitação não corresponde à especialização do subagente
• Contexto do subagente cheio (raro)
• O contexto da conversa principal afetando o roteamento

Solução:

• Use uma @-menção explícita para forçar um subagente específico
• Reformule a solicitação para corresponder à expertise do subagente
• Inicie uma nova conversa se o contexto for um problema

AGENTS.md não aplicado

Problema: as regras do projeto não afetam o comportamento do Verdent

Diagnóstico:

1. Localização: o arquivo deve estar no diretório raiz do projeto
2. Sintaxe: Markdown válido (verifique erros de sintaxe)
3. Especificidade: as regras devem ser diretivas: "Always use X" e não "Try to use X"
4. Teste: inicie uma nova conversa para testar a aplicação do zero

Verificação de precedência:

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

Falhas de conexão do MCP

Erro: não é possível conectar ao servidor MCP

Etapas de diagnóstico:

1. Verifique o mcp.json: sintaxe JSON válida em ~/.verdent/mcp.json
2. Servidor em execução: certifique-se de que o processo do servidor MCP esteja ativo
3. Rede: verifique a conectividade com o endpoint do servidor
4. Autenticação: confirme se as credenciais estão corretas
5. Logs: verifique os logs do servidor MCP para obter detalhes do erro

Correções comuns:

• Reinicie o servidor MCP
• Verifique o formato da string de conexão
• Verifique as regras de firewall que permitem o tráfego do MCP
• Valide as chaves ou tokens do API

Limitações de arquivos binários

Problema: não é possível editar imagens, PDFs, binários compilados

Solução alternativa:

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

Manipulação de arquivos grandes

Problema: arquivos com mais de 10.000 linhas causam problemas de contexto

Solução 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")

Diferenças de comandos entre plataformas

Problema: os comandos bash diferem entre Windows e Unix

Solução alternativa:

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

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

Prática recomendada: use scripts npm para compatibilidade entre plataformas.