Risoluzione dei problemi

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

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:

Controlla i log:

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

Impossibile accedere a Verdent for VS Code

Causa più comune: problema di configurazione del proxy

Soluzione:

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

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 per assistenza. Il team di supporto può esaminare la tua registrazione e fornire indicazioni su come risolvere il problema.

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 per vedere quali modelli sono disponibili nella tua regione

Problemi di prestazioni

Sintomi:

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

Cause comuni e soluzioni:

Messaggi di errore relativi alle immagini

Riferimento rapido per gli errori comuni di elaborazione delle immagini:

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:

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

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:

# 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

La ricerca non restituisce risultati

Problema: grep_file o glob non trovano i file previsti

Controlla la sintassi del pattern:

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

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

Controlla le esclusioni:

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

Distinzione tra maiuscole e minuscole:

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

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

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

AGENTS.md 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:

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

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

Limitazioni dei file binari

Problema: impossibile modificare immagini, PDF, binari compilati

Soluzione alternativa:

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

Gestione dei file di grandi dimensioni

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

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

Differenze nei comandi tra piattaforme

Problema: i comandi bash differiscono tra Windows e Unix

Soluzione alternativa:

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