# Risoluzione dei problemi (/it/docs/verdent-for-vscode/help-support/common-issues)

> Problemi comuni, diagnostica e soluzioni



### Cosa imparerai [#cosa-imparerai]

Procedure comuni di risoluzione dei problemi, passaggi diagnostici e soluzioni alternative per problemi noti di Verdent for VS Code.

<Info>
  La risoluzione dettagliata dei problemi più segnalati dagli utenti è in fase di raccolta a partire dai dati di supporto. Questa pagina fornisce procedure diagnostiche generali. Contatta [support@verdent.ai](mailto:support@verdent.ai) per problemi specifici non trattati qui.
</Info>

***

## Diagnostica rapida [#diagnostica-rapida]

<Tabs>
  <Tab title="Errori di servizio (i più comuni)">
    ### "Service is experiencing high traffic. Please try again later!" [#service-is-experiencing-high-traffic-please-try-again-later]

    **Questo è l'errore n. 1 più comune** che gli utenti incontrano. Indica che il servizio Verdent è temporaneamente sovraccarico.

    **Quando si verifica:**

    * Durante gli orari di utilizzo di punta
    * Quando i servizi backend sono sotto forte carico
    * Degrado temporaneo del servizio

    **Passaggi di ripristino (in ordine):**

    <Steps>
      <Step title="Annulla il messaggio" stepNumber="1">
        Se l'errore persiste, annulla il messaggio più recente:

        * Seleziona il pulsante di annullamento/ripristino nell'interfaccia della chat
        * Reinvia la richiesta dopo una breve attesa
      </Step>

      <Step title="Avvia una nuova sessione" stepNumber="2">
        Se gli errori continuano, avvia una nuova sessione:

        * Seleziona il pulsante "+" (Nuova sessione) nella barra superiore
        * Questo azzera il contesto e le approvazioni degli strumenti
        * Reinvia la richiesta nella sessione pulita
      </Step>

      <Step title="Attendi e riprova" stepNumber="3">
        Attendi 30-60 secondi e riprova la richiesta. La maggior parte dei problemi di servizio si risolve rapidamente.
      </Step>
    </Steps>

    <Warning>
      Se il problema persiste per più di 5-10 minuti su più sessioni, controlla la [pagina di stato di Verdent](https://verdent.ai/status) o contatta [support@verdent.ai](mailto:support@verdent.ai).
    </Warning>
  </Tab>

  <Tab title="Installazione e configurazione">
    ### Problemi di installazione e configurazione [#problemi-di-installazione-e-configurazione]

    **Requisiti di sistema:**

    * **Versione di VS Code:** 1.90.0 o successiva (obbligatoria)
    * **Connessione internet:** connessione attiva richiesta
    * **Abbonamento:** abbonamento Verdent attivo

    **Elenco diagnostico di base:**

    1. **Verifica la versione di VS Code:** Help → About (deve essere 1.90.0+)
    2. **Controlla la connessione internet:** Verdent richiede una connessione attiva
    3. **Verifica l'abbonamento:** assicurati che l'abbonamento Verdent sia attivo
    4. **Riavvia VS Code:** dopo l'installazione o le modifiche di configurazione
    5. **Controlla lo stato dell'estensione:** View → Extensions → Verdent (deve mostrare "Enabled")

    **Procedura di reinstallazione pulita:**

    <Steps>
      <Step title="Disinstalla Verdent">
        View → Extensions → Verdent → Uninstall
      </Step>

      <Step title="Riavvia VS Code">
        Chiudi completamente e riapri VS Code
      </Step>

      <Step title="Reinstalla Verdent">
        View → Extensions → cerca "Verdent" → Install
      </Step>
    </Steps>

    **Controlla i log:**

    * Apri il pannello Output: View → Output
    * Seleziona "Verdent" dal menu a discesa
    * Cerca messaggi di errore o stack trace

    <Info>
      La maggior parte dei problemi di installazione si risolve con un semplice ricaricamento di VS Code o una reinstallazione pulita. Se i problemi persistono, controlla i log e contatta il supporto fornendo i dettagli dei log.
    </Info>
  </Tab>

  <Tab title="Autenticazione e account">
    ### Impossibile accedere a Verdent for VS Code [#impossibile-accedere-a-verdent-for-vs-code]

    **Causa più comune:** problema di configurazione del proxy

    **Soluzione:**

    <Steps>
      <Step title="Apri le impostazioni di VS Code">
        Premi `Cmd+,` (macOS) o `Ctrl+,` (Windows/Linux)
      </Step>

      <Step title="Cerca l'impostazione del proxy">
        Cerca "useProxy" o "verdent.enableProxy" nella barra di ricerca delle impostazioni
      </Step>

      <Step title="Attiva/disattiva lo stato del proxy">
        Attiva o disattiva l'impostazione del proxy (opposto allo stato attuale)
      </Step>

      <Step title="Riprova l'accesso">
        Prova di nuovo ad accedere a Verdent
      </Step>
    </Steps>

    <Info>
      Se ti trovi dietro un firewall aziendale, potresti dover abilitare l'impostazione del proxy. Se sei su una rete domestica, prova a disabilitarla.
    </Info>

    ***

    ### Crediti di prova gratuita non ricevuti [#crediti-di-prova-gratuita-non-ricevuti]

    **Errore:** i crediti della prova gratuita non sono stati ricevuti o l'accesso alla prova gratuita è stato negato

    **Motivo:** rilevata una violazione dei termini di servizio durante la registrazione

    **Risoluzione:** contatta [support@verdent.ai](mailto:support@verdent.ai) per assistenza con l'accesso alla prova gratuita. Il team di supporto esaminerà il tuo account e ti aiuterà a risolvere il problema.

    ***

    ### Registrazione non riuscita [#registrazione-non-riuscita]

    **Errore:** la registrazione dell'account è stata rifiutata o limitata

    **Motivo:** la registrazione ha violato i termini di servizio di Verdent, causando una limitazione dell'accesso

    **Risoluzione:** contatta [support@verdent.ai](mailto:support@verdent.ai) per assistenza. Il team di supporto può esaminare la tua registrazione e fornire indicazioni su come risolvere il problema.

    ***

    ### Modelli mancanti (Claude, GPT, Gemini) [#modelli-mancanti-claude-gpt-gemini]

    **Problema:** impossibile trovare i modelli Claude, GPT o Gemini nella selezione dei modelli

    **Motivo:** restrizioni basate sulla posizione geografica da parte dei provider dei modelli

    **Spiegazione:** alcuni provider di modelli AI hanno restrizioni regionali che impediscono la disponibilità di determinati modelli in specifiche aree geografiche. Quando questo accade:

    * I modelli con restrizioni non compariranno nel menu di selezione dei modelli
    * Puoi comunque usare senza interruzioni tutti gli altri modelli disponibili
    * Nessun impatto sull'abbonamento o sui crediti

    **Controlla i modelli disponibili:** visita [https://www.verdent.ai/regions](https://www.verdent.ai/regions) per vedere quali modelli sono disponibili nella tua regione

    <Note>
      Le restrizioni regionali sono stabilite dai provider dei modelli AI (Anthropic, OpenAI, Google), non da Verdent. Verdent non può ignorare queste restrizioni.
    </Note>
  </Tab>

  <Tab title="Prestazioni">
    ### Problemi di prestazioni [#problemi-di-prestazioni]

    **Sintomi:**

    * Tempi di risposta lenti
    * Errori di finestra di contesto piena
    * Timeout nell'esecuzione degli strumenti

    **Cause comuni e soluzioni:**

    | Problema                       | Causa                                | Soluzione                                                                     |
    | ------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
    | Risposte lente                 | Lettura di file di grandi dimensioni | Usa intervalli di righe: `file_read("file.js", start_line=100, max_lines=50)` |
    | Contesto pieno                 | Cronologia della conversazione lunga | Delega ai sottoagenti o avvia una nuova conversazione                         |
    | Timeout degli strumenti        | Comandi bash a lunga esecuzione      | Imposta un timeout esplicito o suddividi in comandi più piccoli               |
    | Utilizzo elevato della memoria | Troppe operazioni in parallelo       | Limita le esecuzioni concorrenti degli strumenti                              |

    <Tip>
      Delega le attività esplorative al sottoagente @Explorer per preservare il contesto principale.
    </Tip>
  </Tab>

  <Tab title="Errori sulle immagini">
    ### Messaggi di errore relativi alle immagini [#messaggi-di-errore-relativi-alle-immagini]

    **Riferimento rapido per gli errori comuni di elaborazione delle immagini:**

    | Messaggio di errore            | Causa                                                                                                | Soluzione                                                            |
    | ------------------------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
    | **Unsupported Image Type**     | Sono supportate solo immagini JPEG, PNG, GIF o WebP                                                  | Annulla e cambia il tipo di immagine in un formato supportato        |
    | **Image Dimensions Too Large** | La larghezza o l'altezza dell'immagine non può superare gli 8000 pixel                               | Annulla e regola le dimensioni dell'immagine a 8000×8000 o inferiori |
    | **Input Too Long**             | L'input supera la lunghezza massima consentita dal modello                                           | Semplifica l'input o riduci le dimensioni dell'immagine              |
    | **File Too Large**             | La dimensione dell'immagine non può superare i 5 MB                                                  | Annulla e invia un'immagine compressa (max 5 MB)                     |
    | **Unreadable Image**           | Impossibile elaborare l'immagine, il file potrebbe essere danneggiato o in un formato non supportato | Annulla e sostituisci l'immagine con un file valido                  |
  </Tab>
</Tabs>

***

## Problemi specifici degli strumenti [#problemi-specifici-degli-strumenti]

<Tabs>
  <Tab title="Errori di file_edit">
    ### Errori di file\_edit [#errori-di-file_edit]

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

    **Cause:**

    * Il testo è cambiato dall'ultimo file\_read
    * Differenze negli spazi bianchi (tab vs spazi)
    * Stringa non univoca nel file

    **Soluzioni:**

    ```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>
      Leggi sempre il file subito prima di modificarlo per assicurarti di avere lo stato corrente.
    </Warning>
  </Tab>

  <Tab title="Errori di bash">
    ### Errori nei comandi bash [#errori-nei-comandi-bash]

    **Errore:** timeout del comando o errore di esecuzione

    **Timeout massimo:** 120 secondi (2 minuti, limite rigido)

    **Soluzione:** suddividi i comandi lunghi in operazioni più piccole:

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

    **Comando non trovato:**

    * Controlla se il comando esiste: `bash("which command-name")`
    * Assicurati che il percorso sia corretto o attiva prima l'ambiente
    * Usa percorsi completi per gli eseguibili

    **Errori di permessi:**

    * I comandi vengono eseguiti con i permessi dell'utente
    * Usa `sudo` solo se necessario e in Manual Accept Mode
    * Controlla i permessi di file/directory
  </Tab>

  <Tab title="Problemi di ricerca">
    ### La ricerca non restituisce risultati [#la-ricerca-non-restituisce-risultati]

    **Problema:** grep\_file o glob non trovano i file previsti

    **Controlla la sintassi del pattern:**

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

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

    **Controlla le esclusioni:**

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

    **Distinzione tra maiuscole e minuscole:**

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

***

## Problemi di sottoagenti e configurazione [#problemi-di-sottoagenti-e-configurazione]

<Tabs>
  <Tab title="Il sottoagente non si attiva">
    ### Il sottoagente non si attiva [#il-sottoagente-non-si-attiva]

    **Problema:** un sottoagente personalizzato non si attiva automaticamente

    **Elenco di controllo:**

    * Posizione del file: `~/.verdent/subagents/[name].md`
    * Frontmatter YAML valido con `name` e `description`
    * La policy di invocazione corrisponde all'uso (strict richiede la @-menzione)
    * Le linee guida "When to use" corrispondono al pattern della richiesta
    * Nessun errore di sintassi nel file markdown

    **Testa manualmente:**

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

    <Tip>
      Usa una @-menzione esplicita per verificare che il sottoagente funzioni prima di risolvere i problemi di invocazione automatica.
    </Tip>
  </Tab>

  <Tab title="Sottoagenti integrati">
    ### Comportamento dei sottoagenti integrati [#comportamento-dei-sottoagenti-integrati]

    **Problema:** @Explorer, @Verifier o @Code-reviewer non si comportano come previsto

    **Cause comuni:**

    * La richiesta non corrisponde alla specializzazione del sottoagente
    * Contesto del sottoagente pieno (raro)
    * Il contesto della conversazione principale influisce sul routing

    **Soluzione:**

    * Usa una @-menzione esplicita per forzare un sottoagente specifico
    * Riformula la richiesta in modo che corrisponda alle competenze del sottoagente
    * Avvia una nuova conversazione se il contesto è un problema
  </Tab>

  <Tab title="Regole di AGENTS.md">
    ### AGENTS.md non applicato [#agentsmd-non-applicato]

    **Problema:** le regole del progetto non influiscono sul comportamento di Verdent

    **Diagnostica:**

    1. **Posizione:** il file deve trovarsi nella directory principale del progetto
    2. **Sintassi:** Markdown valido (controlla eventuali errori di sintassi)
    3. **Specificità:** le regole devono essere direttive: "Usa sempre X" e non "Prova a usare X"
    4. **Test:** avvia una nuova conversazione per testarne l'applicazione da zero

    **Verifica della precedenza:**

    ```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="Connessione MCP">
    ### Errori di connessione MCP [#errori-di-connessione-mcp]

    **Errore:** impossibile connettersi al server MCP

    **Passaggi diagnostici:**

    1. **Controlla mcp.json:** sintassi JSON valida in `~/.verdent/mcp.json`
    2. **Server in esecuzione:** assicurati che il processo del server MCP sia attivo
    3. **Rete:** verifica la connettività verso l'endpoint del server
    4. **Autenticazione:** conferma che le credenziali siano corrette
    5. **Log:** controlla i log del server MCP per i dettagli dell'errore

    **Soluzioni comuni:**

    * Riavvia il server MCP
    * Verifica il formato della stringa di connessione
    * Controlla le regole del firewall che consentono il traffico MCP
    * Convalida le chiavi o i token API
  </Tab>
</Tabs>

***

## Problemi noti e soluzioni alternative [#problemi-noti-e-soluzioni-alternative]

<Tabs>
  <Tab title="File binari">
    ### Limitazioni dei file binari [#limitazioni-dei-file-binari]

    **Problema:** impossibile modificare immagini, PDF, binari compilati

    **Soluzione alternativa:**

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

    <Info>
      Le modifiche ai file binari richiedono strumenti esterni invocati tramite comandi bash.
    </Info>
  </Tab>

  <Tab title="File di grandi dimensioni">
    ### Gestione dei file di grandi dimensioni [#gestione-dei-file-di-grandi-dimensioni]

    **Problema:** i file con più di 10.000 righe causano problemi di contesto

    **Soluzione 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>
      Cerca prima con grep\_content per individuare i numeri di riga rilevanti, quindi leggi solo quegli intervalli specifici.
    </Tip>
  </Tab>

  <Tab title="Differenze tra piattaforme">
    ### Differenze nei comandi tra piattaforme [#differenze-nei-comandi-tra-piattaforme]

    **Problema:** i comandi bash differiscono tra Windows e Unix

    **Soluzione alternativa:**

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

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

    **Best practice:** usa gli script npm per la compatibilità multipiattaforma.
  </Tab>
</Tabs>

***

## Ottenere ulteriore aiuto [#ottenere-ulteriore-aiuto]

### Canali di supporto [#canali-di-supporto]

**Per problemi specifici non trattati qui:**

* **Email:** [support@verdent.ai](mailto:support@verdent.ai)
* **Discord:** [unisciti alla community di Verdent](https://discord.com/invite/NGjXEZcbJq) per supporto in tempo reale
* **Problemi di GitHub:** segnala bug o richiedi funzionalità

**Quando segnali un problema, includi:**

1. Versione di Verdent (dal pannello Extensions)
2. Versione di VS Code
3. Sistema operativo
4. Messaggi di errore (testo esatto)
5. Passaggi per riprodurre il problema
6. Comportamento previsto rispetto a quello effettivo

***

### Raccolta delle informazioni diagnostiche [#raccolta-delle-informazioni-diagnostiche]

**Per aiutare il supporto nella diagnosi:**

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

***

## Vedi anche [#vedi-anche]

<CardGroup cols="2">
  <Card title="FAQ" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    Domande frequenti
  </Card>

  <Card title="Limitazioni" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    Limitazioni e vincoli noti
  </Card>
</CardGroup>