Gestione e recupero degli errori

Capire come interpretare, rispondere e segnalare gli errori ti aiuta a mantenere sessioni di sviluppo produttive con Verdent for VS Code.

Cosa imparerai

I tipi di errore più comuni e le loro cause
Come interpretare efficacemente i messaggi di errore
Passaggi sistematici per la risoluzione dei problemi
Quando aspettare e quando intervenire
Come segnalare i problemi al team di Verdent

La documentazione completa sugli errori è attualmente in fase di sviluppo. Le informazioni seguenti coprono le categorie di errore più frequenti. Per scenari di errore specifici, contatta support@verdent.ai o visita la community su Discord.

Errori di server sovraccarico

Si verificano nei periodi di traffico elevato
Vincoli temporanei di capacità
Azione: attendi 5-10 minuti e riprova

Errori interni del server

Problemi di elaborazione backend
Interruzioni temporanee del servizio
Azione: attendi e riprova, di solito si risolvono automaticamente

503 Service Unavailable

Nessun server upstream integro
Problemi temporanei dell'infrastruttura
Azione: attendi il ripristino del servizio

Errori di limitazione delle richieste

Quote di richieste superate
Protezioni di throttling di API
Azione: attendi il ripristino del limite, riduci la frequenza delle richieste

Credenziali non valide o scadute
Problemi di timeout della sessione
Azione: autenticati di nuovo tramite l'User Center, verifica che l'abbonamento sia attivo

Problemi di connettività di rete
Firewall o VPN che blocca le connessioni
Restrizioni della rete aziendale
Azione: controlla la connessione di rete, prova una rete diversa

Impostazioni o preferenze non valide
File di configurazione danneggiati
Azione: rivedi le recenti modifiche alle impostazioni, verifica la configurazione

Autorizzazioni del file system insufficienti
Restrizioni di accesso al workspace
Azione: controlla le autorizzazioni di file/cartelle, verifica l'accesso al workspace

Interpretare i messaggi di errore

La guida dettagliata all'interpretazione dei messaggi di errore è in fase di sviluppo. Per messaggi di errore specifici che incontri, usa il pulsante Feedback o la community su Discord per ricevere assistenza.

Gli errori lato server sono temporanei e di solito si risolvono con l'attesa. Non è richiesta alcuna azione oltre a riprovare dopo qualche minuto.

Cerca queste parole chiave:

"Overloaded" o "at capacity"
"Internal server error" o "backend processing"
"503 Service Unavailable" o "no healthy upstream"
"Rate limit" o "quota"

Cosa fare:

Attendi 5-10 minuti prima di riprovare
Continua il lavoro di sviluppo in locale
Rivedi le modifiche al codice fatte finora
Fai il commit del lavoro corrente su Git

Regola generale: se il messaggio di errore menziona lo stato del server, la capacità o i limiti di richieste, è temporaneo. Sono problemi di infrastruttura che si risolvono automaticamente.

Gli errori temporanei del server (502, 503, 504) di solito si risolvono in pochi minuti. Attendi 2-3 minuti prima di riprovare.

Quando fare escalation:

L'errore persiste oltre i 15 minuti
Controlla su Discord se ci sono segnalazioni di interruzioni
Cerca aggiornamenti sulla pagina di stato

Gli errori lato client richiedono un tuo intervento. Non si risolvono con l'attesa.

Cerca questi indicatori:

Messaggi relativi all'autenticazione o alle credenziali
Errori di configurazione o impostazioni
Errori di autorizzazione dei file
Errori di connessione di rete

Cosa fare:

Errori di autenticazione: autenticati di nuovo tramite l'User Center, verifica che l'abbonamento sia attivo
Errori di configurazione: rivedi le recenti modifiche alle impostazioni, verifica i file di configurazione
Errori di autorizzazione: controlla le autorizzazioni di file/cartelle, verifica l'accesso al workspace
Errori di rete: verifica la connessione a internet, prova una rete diversa, controlla VPN/firewall

Regola generale: se l'errore menziona autenticazione, configurazione, autorizzazioni o impostazioni locali, devi intervenire per correggerlo.

Passaggi per la risoluzione dei problemi:

Leggi l'intero messaggio di errore per indicazioni specifiche
Identifica quale componente ha segnalato l'errore (autenticazione, configurazione, autorizzazioni, rete)
Intervieni in modo mirato in base al tipo di errore
Verifica la correzione riprovando l'operazione originale

Leggere il contesto dell'errore

Quando si verificano errori:

Leggi l'intero messaggio di errore – Non saltare i dettagli
Prendi nota dei codici di errore – Codici specifici aiutano a diagnosticare i problemi
Identifica il componente – Quale sistema ha segnalato l'errore (server, API, locale)
Controlla i tempi – È successo subito o dopo un ritardo?

Risoluzione sistematica dei problemi

Segui questi passaggi progressivi quando Verdent si comporta in modo imprevisto, iniziando dalle azioni meno invasive.

Risposta iniziale

Aspetta e osserva

Verifica se il comportamento è costante o intermittente. Prendi nota di quale azione ha innescato il comportamento imprevisto. Non dare per scontato che qualcosa sia rotto: molti problemi sono temporanei.

Riavvio di base

Riavvia Verdent for VS Code (chiudi e riapri VS Code). Spesso risolve stati bloccati o problemi di prestazioni. È il primo e più semplice passaggio di risoluzione dei problemi.

Risoluzione progressiva dei problemi

Se il riavvio di base non risolve il problema:

Segui i passaggi di risoluzione dei problemi nell'ordine: saltare dei passaggi spesso significa non individuare la causa principale.

Controlla la connessione di rete

Verifica la connessione a internet con altri siti. Prova su una rete diversa (hotspot da telefono) per escludere problemi di firewall/VPN. Controlla se la rete aziendale sta bloccando le connessioni.

Verifica la configurazione

Controlla di essere ancora autenticato. Verifica che l'abbonamento sia attivo nell'User Center. Rivedi le recenti modifiche alle impostazioni che potrebbero influire sul comportamento.

Cerca aiuto

Controlla nella community su Discord se ci sono segnalazioni simili: https://discord.com/invite/NGjXEZcbJq. Usa il pulsante Feedback per segnalare il problema. Includi una descrizione del comportamento imprevisto e i passaggi per riprodurlo.

Cosa NON fare

Evita queste azioni per problemi temporanei:

Non reinstallare subito Verdent
Non svuotare la cache di VS Code o i dati dell'applicazione
Non modificare le impostazioni di sistema per problemi temporanei
Non riavviare il computer a meno che non siano coinvolte anche altre applicazioni

In Manual Accept Mode, non approvare mai operazioni distruttive (rm, DROP, DELETE) senza aver esaminato con attenzione il comando esatto.

Perché? Queste azioni richiedono tempo e raramente risolvono i problemi. La maggior parte dei problemi si risolve con un semplice riavvio o aspettando che i problemi temporanei del server si risolvano.

Quando aspettare e quando intervenire

Capire se aspettare o intervenire evita di sprecare tempo nella risoluzione dei problemi.

Questi errori si risolvono automaticamente: non serve alcuna azione oltre ad aspettare e riprovare.

Errori di sovraccarico o capacità del server:

Messaggi "Overloaded" o "at capacity"
Periodi di traffico elevato
Interruzioni temporanee del servizio

Limitazione delle richieste:

Messaggi "Rate limit" o "quota exceeded"
Troppe richieste in poco tempo
Protezione di throttling di API

Problemi di connessione intermittenti:

Richieste occasionalmente fallite che riescono al nuovo tentativo
Interruzioni momentanee di rete
Brevi cadute di connettività

Cosa fare mentre aspetti:

Continua il lavoro di sviluppo in locale
Rivedi le modifiche al codice fatte finora
Pianifica i passaggi successivi o le cose da fare
Fai il commit del lavoro corrente su Git

Quanto aspettare:

Attesa standard: 5-10 minuti
Se dopo 10 minuti continua a fallire, passa alla risoluzione dei problemi
Controlla su Discord se ci sono segnalazioni di problemi diffusi

Questi errori non si risolvono con l'attesa: devi intervenire per correggerli.

Errori di autenticazione:

Sessione scaduta → autenticati di nuovo tramite l'User Center
Credenziali non valide → verifica che l'abbonamento sia attivo
Necessità di autenticarsi di nuovo → controlla l'User Center

Errori persistenti (oltre 10 minuti):

Stesso errore ripetuto dopo più tentativi → avvia la risoluzione dei problemi
Schema di errore costante → controlla la configurazione
L'errore persiste dopo i riavvii → verifica l'ambiente

Problemi di configurazione:

Impostazioni modificate di recente → rivedi e annulla le modifiche
Nuova configurazione o installazione → verifica i file di configurazione
Ambiente di rete cambiato → verifica la connettività

Errori di autorizzazione:

Accesso al file system negato → controlla le autorizzazioni di file/cartelle
Restrizioni del workspace → verifica l'accesso al workspace
Autorizzazioni delle cartelle → concedi le autorizzazioni necessarie

Problemi di rete:

Impossibilità totale di connettersi → verifica la connessione a internet
VPN o firewall che bloccano → prova una rete diversa
Restrizioni della rete aziendale → contatta il supporto IT

Regola decisionale:

Errori di server/limiti → aspetta
Autenticazione/configurazione/autorizzazioni/rete → intervieni subito
Non sei sicuro? → aspetta prima 5-10 minuti, poi intervieni se persiste

Fornire il contesto dell'errore

Quando cerchi aiuto o segnali problemi, includi un contesto completo per una diagnosi più rapida.

Informazioni essenziali

Dettagli dell'errore:

Testo esatto del messaggio di errore (copia e incolla, non parafrasare)
Codice di errore se presente
Data e ora in cui si è verificato l'errore
Frequenza (una tantum, intermittente, costante)

Ambiente:

Versione di Verdent for VS Code
Versione di VS Code
Sistema operativo e versione
Ambiente di rete (casa, azienda, VPN)

Passaggi per riprodurre:

Cosa stavi cercando di fare
Prompt o comandi esatti usati
File o contesto coinvolti
Azioni eseguite prima dell'errore

Contesto:

Quale modalità di esecuzione stavi usando
Dimensione e complessità del workspace
Modifiche recenti alla configurazione
Operazioni simili riuscite in precedenza

Esempio di segnalazione di errore

Formato efficace per una segnalazione di errore:

Issue: Getting "Internal server error" when requesting code analysis

Error Message (exact):
"Error: Internal server error occurred during processing. Please try again later."

Environment:
- Verdent for VS Code v1.2.3
- VS Code 1.85.0
- macOS 14.2
- Home network (no VPN)

Steps to Reproduce:
1. Opened large TypeScript project (500+ files)
2. Used Auto-Run Mode
3. Requested: "Analyze authentication flow in auth.ts and suggest improvements"
4. Error occurred immediately after request

Additional Context:
- First time working with this project
- Same request worked fine yesterday in different project
- Other requests (small file edits) work normally

Cosa lo rende efficace

Testo esatto del messaggio di errore
Dettagli completi dell'ambiente
Passaggi di riproduzione chiari
Confronto con scenari funzionanti
Contesto aggiuntivo sugli schemi ricorrenti

Segnalare i problemi

Posizione: barra superiore del pannello Verdent

Cosa fa:

Apre un overlay a comparsa per inviare problemi e suggerimenti
Canale diretto con il team di Verdent
Ideale per segnalazioni di bug e richieste di funzionalità

Quando usarlo:

Bug confermati con passaggi di riproduzione chiari
Richieste di funzionalità con casi d'uso specifici
Necessità di comunicazione diretta con il team
Problemi non urgenti che richiedono un'indagine

Cosa includere:

Descrizione chiara del problema
Messaggi di errore (testo esatto)
Passaggi per riprodurre
Comportamento atteso vs comportamento effettivo
Versione di Verdent e piattaforma
Quando è iniziato il problema

Link: https://discord.com/invite/NGjXEZcbJq

Cosa offre:

Community attiva di utenti e membri del team di Verdent
Assistenza in tempo reale nella risoluzione dei problemi
Condivisione di problemi con screenshot
Aiuto da utenti esperti
Discussione nella community e soluzioni alternative

Quando usarla:

Problemi urgenti che richiedono una discussione immediata
Risoluzione complessa che richiede scambi ripetuti
Confronto con la community sulle best practice
Domande rapide prima di inviare segnalazioni formali
Condivisione di soluzioni alternative con la community

Tipo di problema	Usa il pulsante Feedback	Usa Discord
Bug confermato con passaggi di riproduzione	✓
Richiesta di funzionalità	✓
Risoluzione urgente necessaria		✓
Problema complesso che richiede discussione		✓
Domanda rapida		✓
Desiderio di un confronto con la community		✓
Segnalazione formale di bug	✓
Aiuto generico		✓

Cosa NON segnalare:

Errori temporanei del server (< 10 minuti)
Periodi di traffico elevato
Problemi già documentati
Comportamento previsto

Invece: aspetta la risoluzione dei problemi temporanei, controlla su Discord le segnalazioni recenti, consulta la documentazione.

Best practice di prevenzione

Le pratiche proattive riducono la frequenza degli errori e migliorano il recupero quando si verificano.

Usa un linguaggio specifico nei prompt e includi il contesto dei file pertinenti per prevenire molti errori comuni prima che si verifichino.

Prima di iniziare a lavorare

1. Verifica la configurazione

Controlla lo stato di autenticazione nell'User Center
Conferma che l'abbonamento sia attivo
Assicurati di avere una connessione di rete stabile
Rivedi le recenti modifiche alla configurazione

2. Inizializza Git

Abbi sempre un controllo di versione prima di usare le modalità più permissive
Fai il commit del lavoro corrente per un punto di partenza pulito
Offre un'opzione di rollback in caso di problemi

3. Controlla il saldo dei crediti

Verifica di avere crediti sufficienti per il lavoro pianificato
Ricarica se necessario prima di iniziare attività complesse
Evita interruzioni a metà attività per esaurimento dei crediti

Durante lo sviluppo

1. Usa le modalità di esecuzione appropriate

Manual Accept per codice non familiare
Plan Mode per modifiche complesse
Auto-Run solo con la rete di sicurezza di Git
Adatta la modalità al livello di rischio

2. Monitora le prestazioni

Fai attenzione al calo di qualità delle risposte
Prendi nota dei tempi di risposta più lenti
Avvia sessioni nuove quando le prestazioni calano
Tieni traccia manualmente dell'uso del contesto

3. Prompt chiari e specifici

Riducono gli errori dovuti a richieste fraintese
Includi contesto e vincoli pertinenti
Fai riferimento a pattern esistenti
Specifica chiaramente l'ambito

Dopo gli errori

1. Impara dagli schemi ricorrenti

Prendi nota di cosa ha innescato gli errori
Individua le condizioni riproducibili
Adatta il flusso di lavoro per evitare gli inneschi
Condividi ciò che scopri con la community

2. Documenta le soluzioni alternative

Conserva appunti sulle soluzioni efficaci
Condividi con i membri del team
Contribuisci alla conoscenza della community
Segnala al team di Verdent per le correzioni

3. Aggiorna la configurazione

Modifica le impostazioni in base all'esperienza
Ottimizza per il tuo flusso di lavoro
Configura le regole per prevenire i problemi
Mantieni aggiornata la documentazione AGENTS.md