---
title: "Solução de problemas"
description: "Problemas comuns, diagnósticos e soluções"
---

### O que você vai aprender

Procedimentos comuns de solução de problemas, etapas de diagnóstico e soluções alternativas para problemas conhecidos do Verdent for VS Code.

<Info>
  A solução detalhada para os principais problemas relatados pelos usuários está sendo compilada a partir dos dados de suporte. Esta página fornece procedimentos gerais de diagnóstico. Entre em contato com [support@verdent.ai](mailto:support@verdent.ai) para problemas específicos não abordados aqui.
</Info>

---

## Diagnósticos rápidos

<Tabs>
  <Tab title="Erros de serviço (mais comuns)">
    ### "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):**

    <Steps>
      <Step title="Reverter mensagem" stepNumber={1}>
        Se o erro persistir, reverta a mensagem mais recente:

        - Clique no botão de reverter/desfazer na interface de chat
        - Reenvie sua solicitação após uma breve espera
      </Step>
      <Step title="Iniciar nova sessão" stepNumber={2}>
        Se os erros continuarem, inicie uma nova sessão:

        - Clique no botão "+" (Nova sessão) na barra superior
        - Isso limpa o contexto e as aprovações de ferramentas
        - Reenvie sua solicitação na sessão limpa
      </Step>
      <Step title="Aguardar e tentar novamente" stepNumber={3}>
        Aguarde de 30 a 60 segundos e tente sua solicitação novamente. A maioria dos problemas de serviço se resolve rapidamente.
      </Step>
    </Steps>
    <Warning>
      Se o problema persistir por mais de 5 a 10 minutos em várias sessões, verifique a [página de status do Verdent](https://verdent.ai/status) ou entre em contato com [support@verdent.ai](mailto:support@verdent.ai).
    </Warning>
  </Tab>
  <Tab title="Instalação e configuração">
    ### 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:**

    <Steps>
      <Step title="Desinstale o Verdent">
        View → Extensions → Verdent → Uninstall
      </Step>
      <Step title="Reinicie o VS Code">
        Feche e reabra completamente o VS Code
      </Step>
      <Step title="Reinstale o Verdent">
        View → Extensions → Pesquise "Verdent" → Install
      </Step>
    </Steps>
    **Verifique os logs:**

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

    <Info>
      A maioria dos problemas de instalação se resolve com um simples recarregamento do VS Code ou uma reinstalação limpa. Se os problemas persistirem, verifique os logs e entre em contato com o suporte com os detalhes do log.
    </Info>
  </Tab>
  <Tab title="Autenticação e conta">
    ### Não consigo fazer login no Verdent for VS Code

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

    **Solução:**

    <Steps>
      <Step title="Abra as configurações do VS Code">
        Pressione `Cmd+,` (macOS) ou `Ctrl+,` (Windows/Linux)
      </Step>
      <Step title="Pesquise a configuração de proxy">
        Pesquise "useProxy" ou "verdent.enableProxy" na barra de pesquisa de configurações
      </Step>
      <Step title="Alterne o status do proxy">
        Alterne a configuração de proxy (oposta ao estado atual)
      </Step>
      <Step title="Tente o login novamente">
        Tente fazer login no Verdent novamente
      </Step>
    </Steps>
    <Info>
      Se você estiver atrás de um firewall corporativo, talvez precise habilitar a configuração de proxy. Se estiver em uma rede doméstica, tente desabilitá-la.
    </Info>
    ---

    ### 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](mailto: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](mailto: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

    <Note>
      As restrições regionais são definidas pelos provedores de modelos de IA (Anthropic, OpenAI, Google), não pelo Verdent. O Verdent não pode anular essas restrições.
    </Note>
  </Tab>
  <Tab title="Desempenho">
    ### 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:**

    | Problema             | Causa                        | Solução                                                              |
    | ----------------- | ---------------------------- | --------------------------------------------------------------------- |
    | Respostas lentas    | Arquivos grandes sendo lidos       | Use intervalos de linha: `file_read("file.js", start_line=100, max_lines=50)` |
    | Contexto cheio      | Histórico de conversa longo    | Delegue a subagentes ou inicie uma nova conversa                       |
    | Tempos limite de ferramentas     | Comandos bash de longa duração   | Defina um tempo limite explícito ou divida em comandos menores                   |
    | Alto uso de memória | Muitas operações paralelas | Limite as execuções simultâneas de ferramentas                                      |

    <Tip>
      Delegue tarefas exploratórias ao subagente @Explorer para preservar o contexto principal.
    </Tip>
  </Tab>
  <Tab title="Erros de imagem">
    ### Mensagens de erro relacionadas a imagens

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

    | Mensagem de erro                  | Causa                                                                    | Solução                                                      |
    | ------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
    | **Unsupported Image Type**     | Apenas imagens JPEG, PNG, GIF ou WebP são suportadas                        | Reverta e altere o tipo de imagem para um formato suportado     |
    | **Image Dimensions Too Large** | A largura ou altura da imagem não pode exceder 8000 pixels                          | Reverta e ajuste as dimensões da imagem para 8000×8000 ou menores |
    | **Input Too Long**             | A entrada excede o comprimento máximo permitido pelo modelo                     | Simplifique sua entrada ou reduza o tamanho da imagem                      |
    | **File Too Large**             | O tamanho da imagem não pode exceder 5 MB                                            | Reverta e envie uma imagem comprimida (máx. 5 MB)              |
    | **Unreadable Image**           | Não foi possível processar a imagem, o arquivo pode estar corrompido ou em formato não suportado | Reverta e substitua a imagem por um arquivo válido             |
  </Tab>
</Tabs>

---

## Problemas específicos de ferramentas

<Tabs>
  <Tab title="Falhas de file_edit">
    ### 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:**

    ```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>
      Sempre leia o arquivo imediatamente antes de editar para garantir que você tenha o estado atual.
    </Warning>
  </Tab>
  <Tab title="Falhas de bash">
    ### 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:

    ```bash
    # 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
  </Tab>
  <Tab title="Problemas de pesquisa">
    ### Pesquisa não retorna resultados

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

    **Verifique a sintaxe do padrão:**

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

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

    **Verifique as exclusões:**

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

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

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

---

## Problemas de subagentes e configuração

<Tabs>
  <Tab title="Subagente não é invocado">
    ### 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
    ```

    <Tip>
      Use uma @-menção explícita para verificar se o subagente funciona antes de solucionar a invocação automática.
    </Tip>
  </Tab>
  <Tab title="Subagentes integrados">
    ### 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
  </Tab>
  <Tab title="Regras do AGENTS.md">
    ### 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:**

    ```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="Conexão do MCP">
    ### 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
  </Tab>
</Tabs>

---

## Problemas conhecidos e soluções alternativas

<Tabs>
  <Tab title="Arquivos binários">
    ### Limitações de arquivos binários

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

    **Solução alternativa:**

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

    <Info>
      Modificações em arquivos binários exigem ferramentas externas invocadas por meio de comandos bash.
    </Info>
  </Tab>
  <Tab title="Arquivos grandes">
    ### Manipulação de arquivos grandes

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

    **Solução 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>
      Pesquise primeiro com grep_content para localizar os números de linha relevantes e, em seguida, leia apenas esses intervalos específicos.
    </Tip>
  </Tab>
  <Tab title="Diferenças de plataforma">
    ### Diferenças de comandos entre plataformas

    **Problema:** os comandos bash diferem entre Windows e Unix

    **Solução 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ática recomendada:** use scripts npm para compatibilidade entre plataformas.
  </Tab>
</Tabs>

---

## Obtendo ajuda adicional

### Canais de suporte

**Para problemas específicos não abordados aqui:**

- **E-mail:** [support@verdent.ai](mailto:support@verdent.ai)
- **Discord:** [Junte-se à comunidade do Verdent](https://discord.com/invite/NGjXEZcbJq) para suporte em tempo real
- **Problemas no GitHub:** relate bugs ou solicite recursos

**Ao relatar problemas, inclua:**

1. Versão do Verdent (no painel de Extensions)
2. Versão do VS Code
3. Sistema operacional
4. Mensagens de erro (texto exato)
5. Etapas para reproduzir
6. Comportamento esperado vs. real

---

### Coleta de informações de diagnóstico

**Para ajudar o suporte 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
```

---

## Veja também

<CardGroup cols={2}>
  <Card title="Perguntas frequentes" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    Perguntas frequentes
  </Card>
  <Card title="Limitações" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    Limitações e restrições conhecidas
  </Card>
</CardGroup>