Salta ai contenuti
Vikasit Code
app.header.homeapp.header.docs

Risoluzione dei problemi

Problemi comuni e come risolverli.

Per diagnosticare problemi con Vikasit Code, inizia controllando i log e i dati locali che salva su disco.

Log

I file di log vengono scritti in:

  • macOS/Linux: ~/.local/share/opencode/log/
  • Windows: premi WIN+R e incolla %USERPROFILE%\.local\share\vikasit\log

I file di log hanno nomi con timestamp (ad es. 2025-01-09T123456.log) e vengono conservati i 10 file di log piu recenti.

Puoi impostare il livello di log con l’opzione a riga di comando --log-level per ottenere informazioni di debug piu dettagliate. Per esempio: vikasit --log-level DEBUG.

Archiviazione

vikasit salva i dati delle sessioni e altri dati dell’applicazione su disco in:

  • macOS/Linux: ~/.local/share/opencode/
  • Windows: premi WIN+R e incolla %USERPROFILE%\.local\share\vikasit

Questa directory contiene:

  • auth.json - dati di autenticazione come chiavi API, token OAuth
  • log/ - log dell’applicazione
  • project/ - dati specifici del progetto come dati di sessione e messaggi
    • Se il progetto e dentro un repository Git, viene salvato in ./<project-slug>/storage/
    • Se non e un repository Git, viene salvato in ./global/storage/

App desktop

Vikasit Code Desktop esegue in background un server locale di Vikasit Code (il sidecar opencode-cli). La maggior parte dei problemi e causata da un plugin che si comporta male, da una cache corrotta o da un’impostazione del server errata.

Controlli rapidi

  • Chiudi completamente l’app e riaprila.
  • Se l’app mostra una schermata di errore, fai clic su Restart e copia i dettagli dell’errore.
  • Solo macOS: menu Vikasit Code -> Reload Webview (utile se l’interfaccia e vuota o bloccata).

Disabilita i plugin

Se l’app desktop va in crash all’avvio, si blocca o si comporta in modo strano, inizia disabilitando i plugin.

Controlla la configurazione globale

Apri il tuo file di configurazione globale e cerca la chiave plugin.

  • macOS/Linux: ~/.config/opencode/vikasit.jsonc (o ~/.config/opencode/vikasit.json)
  • macOS/Linux (installazioni vecchie): ~/.local/share/opencode/vikasit.jsonc
  • Windows: premi WIN+R e incolla %USERPROFILE%\.config\vikasit\vikasit.jsonc

Se hai plugin configurati, disabilitali temporaneamente rimuovendo la chiave o impostandola a un array vuoto:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

Controlla le directory dei plugin

Vikasit Code puo anche caricare plugin locali dal disco. Spostali temporaneamente altrove (o rinomina la cartella) e riavvia l’app desktop:

  • Plugin globali
    • macOS/Linux: ~/.config/opencode/plugins/
  • Windows: premi WIN+R e incolla %USERPROFILE%\.config\vikasit\plugins
  • Plugin del progetto (solo se usi una configurazione per progetto)
    • <your-project>/.vikasit/plugins/

Se l’app ricomincia a funzionare, riabilita i plugin uno alla volta per capire quale stia causando il problema.

Svuota la cache

Se disabilitare i plugin non aiuta (o l’installazione di un plugin e bloccata), svuota la cache in modo che Vikasit Code possa ricostruirla.

  1. Chiudi completamente Vikasit Code Desktop.
  2. Elimina la directory della cache:
  • macOS: Finder -> Cmd+Shift+G -> paste ~/.cache/opencode
  • Linux: elimina ~/.cache/opencode (oppure esegui rm -rf ~/.cache/opencode)
  • Windows: premi WIN+R e incolla %USERPROFILE%\.cache\vikasit
  1. Riavvia Vikasit Code Desktop.

Risolvi problemi di connessione al server

Vikasit Code Desktop puo avviare il proprio server locale (predefinito) oppure connettersi a un URL server che hai configurato.

Se vedi una finestra “Connection Failed” (o l’app non supera mai la schermata di avvio), controlla se hai impostato un URL server personalizzato.

Cancella l’URL del server predefinito dell’app desktop

Dalla schermata Home, fai clic sul nome del server (con il pallino di stato) per aprire il selettore dei server. Nella sezione Default server, fai clic su Clear.

Rimuovi server.port / server.hostname dalla tua configurazione

Se il tuo vikasit.json(c) contiene una sezione server, rimuovila temporaneamente e riavvia l’app desktop.

Controlla le variabili d’ambiente

Se hai VIKASIT_PORT impostato nell’ambiente, l’app desktop provera a usare quella porta per il server locale.

  • Rimuovi VIKASIT_PORT (o scegli una porta libera) e riavvia.

Linux: problemi Wayland / X11

Su Linux, alcune configurazioni Wayland possono causare finestre vuote o errori del compositor.

  • Se sei su Wayland e l’app e vuota o va in crash, prova ad avviarla con OC_ALLOW_WAYLAND=1.
  • Se peggiora la situazione, rimuovilo e prova invece ad avviare sotto una sessione X11.

Windows: runtime WebView2

Su Windows, Vikasit Code Desktop richiede WebView2 Runtime di Microsoft Edge. Se l’app si apre su una finestra vuota o non parte, installa/aggiorna WebView2 e riprova.

Windows: problemi generali di prestazioni

Se riscontri prestazioni lente, problemi di accesso ai file o problemi del terminale su Windows, prova a usare WSL (Windows Subsystem for Linux). WSL fornisce un ambiente Linux che funziona in modo piu fluido con le funzionalita di Vikasit Code.

Notifiche non visualizzate

Vikasit Code Desktop mostra le notifiche di sistema solo quando:

  • le notifiche sono abilitate per Vikasit Code nelle impostazioni del sistema operativo, e
  • la finestra dell’app non e in primo piano.

Reimposta lo stato dell’app desktop (ultima risorsa)

Se l’app non si avvia e non riesci a ripulire le impostazioni dall’interfaccia, reimposta lo stato salvato dell’app desktop.

  1. Chiudi Vikasit Code Desktop.
  2. Trova ed elimina questi file (si trovano nella directory dati dell’app Vikasit Code Desktop):
  • vikasit.settings.dat (desktop default server URL)
  • vikasit.global.dat e vikasit.workspace.*.dat (stato dell’interfaccia come server/progetti recenti)

Per trovare rapidamente la directory:

  • macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (poi cerca i nomi file qui sopra)
  • Linux: cerca sotto ~/.local/share i nomi file qui sopra
  • Windows: premi WIN+R -> %APPDATA% (poi cerca i nomi file qui sopra)

Ottenere aiuto

Se riscontri problemi con Vikasit Code:

  1. Segnala i problemi su GitHub

    Il modo migliore per segnalare bug o richiedere funzionalita e tramite il nostro repository GitHub:

    github.com/Vikasit-AI/vikasit-code/issues

    Prima di creare una nuova issue, cerca tra quelle esistenti per vedere se il problema e gia stato segnalato.

  2. Unisciti al nostro Discord

    Per supporto in tempo reale e discussioni con la community, unisciti al nostro server Discord:

    vikasit.ai/discord

Problemi comuni

Ecco alcuni problemi comuni e come risolverli.

Vikasit Code non si avvia

  1. Controlla i log per eventuali messaggi di errore
  2. Prova a eseguire con --print-logs per vedere l’output nel terminale
  3. Assicurati di avere l’ultima versione con vikasit upgrade

Problemi di autenticazione

  1. Prova a riautenticarti con il comando /connect nella TUI
  2. Controlla che le chiavi API siano valide
  3. Assicurati che la rete permetta connessioni all’API del provider

Modello non disponibile

  1. Controlla di esserti autenticato con il provider
  2. Verifica che il nome del modello nella configurazione sia corretto
  3. Alcuni modelli potrebbero richiedere accessi o abbonamenti specifici

Se incontri ProviderModelNotFoundError, probabilmente stai facendo riferimento a un modello in modo errato da qualche parte. I modelli vanno indicati in questo formato: <providerId>/<modelId>

Esempi:

  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • vikasit/kimi-k2

Per capire a quali modelli hai accesso, esegui vikasit models

ProviderInitError

Se incontri un ProviderInitError, probabilmente la tua configurazione e invalida o corrotta.

Per risolvere:

  1. Per prima cosa, verifica che il provider sia configurato correttamente seguendo la guida ai provider

  2. Se il problema persiste, prova a cancellare la configurazione salvata:

    Terminal window
    rm -rf ~/.local/share/opencode

    Su Windows, premi WIN+R ed elimina: %USERPROFILE%\.local\share\vikasit

  3. Riautenticati con il provider usando il comando /connect nella TUI.

AI_APICallError e problemi dei pacchetti provider

Se incontri errori nelle chiamate API, potrebbe dipendere da pacchetti provider non aggiornati. vikasit installa dinamicamente i pacchetti provider (OpenAI, Anthropic, Google, ecc.) quando servono e li mette in cache localmente.

Per risolvere problemi coi pacchetti provider:

  1. Svuota la cache dei pacchetti provider:

    Terminal window
    rm -rf ~/.cache/opencode

    Su Windows, premi WIN+R ed elimina: %USERPROFILE%\.cache\vikasit

  2. Riavvia vikasit per reinstallare i pacchetti provider piu recenti

Questo forzera vikasit a scaricare le versioni piu recenti dei pacchetti provider, cosa che spesso risolve problemi di compatibilita con parametri dei modelli e cambiamenti delle API.

Copia/incolla non funziona su Linux

Su Linux e necessario avere installata una delle seguenti utility per gli appunti affinche copia/incolla funzioni:

Per sistemi X11:

Terminal window
apt install -y xclip
# or
apt install -y xsel

Per sistemi Wayland:

Terminal window
apt install -y wl-clipboard

Per ambienti headless:

Terminal window
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

vikasit rilevera se stai usando Wayland e preferira wl-clipboard; altrimenti provera a trovare gli strumenti per gli appunti nell’ordine: xclip e xsel.