Risoluzione dei problemi

Questa pagina raccoglie i problemi più comuni e le relative soluzioni. Per ogni sintomo sono indicati la causa probabile e i passi per risolverlo.

Autenticazione fallita / token non valido

Sintomo: la connessione al repository fallisce con un errore di autenticazione; la dashboard mostra Connessione fallita o un messaggio di credenziali non valide.

Causa: il token di accesso personale (PAT) è scaduto, revocato o privo dei permessi necessari.

Soluzione:

1. Sul tuo provider git (GitHub, GitLab, Gitea, Azure DevOps…) genera un nuovo PAT con permessi di lettura e scrittura sul repository.
2. Nella dashboard, scheda Sistema → Cambia repo (oppure usa il comando Claude Sync: Configura repository dalla Command Palette).
3. Aggiorna URL, nome utente e token, poi premi Connetti.
4. Ricarica VS Code se richiesto.

Stato “Modifiche in attesa di invio” / “Da inviare ↑N”

Sintomo: la barra superiore della dashboard mostra Modifiche in attesa di invio (o Da inviare ↑N) in modo persistente, anche dopo ripetute sincronizzazioni.

Causa: ci sono commit locali non ancora inviati al repository remoto.

Soluzione:

1. Premi Sincronizza ora: l’engine esegue un pull prima del push.
2. Se persiste, apri la scheda Sistema → Mostra log: un eventuale conflitto reale viene riportato lì (mai risolto di nascosto). Controlla anche la connettività di rete e che il token sia ancora valido.
3. Come ultima risorsa, usa Reset nella scheda Sistema per ri-clonare il clone locale.

Nota

Su una macchina con ruolo membro (sola lettura sul CORE) lo stato si normalizza da solo dopo il ciclo successivo: il membro non autora la configurazione condivisa.

Due macchine possono sovrascriversi a vicenda?

Sintomo: dubbio che una macchina, sincronizzando, cancelli il lavoro fatto su un’altra.

Causa: preoccupazione legittima quando più macchine condividono lo stesso repository.

Soluzione: non può accadere. Non esiste force-push. Quando le macchine divergono, lo strumento riconcilia in modo additivo ciò che può unire — le memorie e i file condivisi accumulativi — e segnala il resto nella dashboard per una decisione umana. Nulla viene sovrascritto in silenzio.

Nota

KoNiMa Claude Sync non esegue mai force-push. I conflitti vengono mostrati nella dashboard e non vengono mai risolti sovrascrivendo il lavoro altrui.

Push rifiutato

Sintomo: la sincronizzazione si avvia ma termina con un errore; il log mostra push rejected o non-fast-forward update.

Causa: il repository remoto ha ricevuto commit da un’altra macchina non ancora integrati localmente, oppure la cronologia locale è divergente.

Soluzione:

1. Premi Sincronizza ora dalla dashboard — l’engine esegue un pull prima del push.
2. Se l’errore persiste, apri la scheda Sistema → Reset per azzerare e ri-clonare il clone locale (sicuro: la fonte di verità è sempre ~/.claude).
3. Se la cronologia è ingombrante, usa Compatta cronologia per riportarla a uno stato pulito (la vecchia storia resta raggiungibile tramite un recovery ref).

Le memorie non si sincronizzano

Sintomo: le memorie di progetto non compaiono su una macchina, oppure le osservazioni locali non vengono inviate al repository.

Causa: una di queste — (a) claude-mem non è installato, (b) gli interruttori di sincronizzazione memoria sono disattivati, (c) l’edizione non include le memorie (disponibili solo in Pro e Team).

Soluzione:

1. Apri la dashboard, scheda Memoria.
2. Se compare la sezione claude-mem non installato, copia il comando di installazione (claude plugin install claude-mem@thedotmack) e avvialo dal terminale.
3. Verifica che gli interruttori Sincronizza le memorie claude-mem (database) e Sincronizza le memorie .md dei progetti siano attivi.
4. Se la scheda Memoria non è presente, la tua edizione non include le memorie — considera l’aggiornamento a Pro o Team.
5. Premi Sincronizza ora per forzare un ciclo completo.

Lo stesso progetto è in cartelle diverse su due macchine

Sintomo: lo stesso progetto è clonato in percorsi locali differenti su macchine diverse, e ci si chiede se le memorie verranno comunque associate correttamente.

Causa: è un caso previsto: il percorso locale può cambiare da macchina a macchina.

Soluzione: non serve fare nulla. Il progetto è identificato dal suo remote git e la memoria viene rimappata sulla cartella locale di ciascuna macchina. La rimappatura è visibile nella scheda Progetti, dove per ogni progetto compare l’elenco macchina → percorso locale.

Attenzione

Un progetto senza remote git non può viaggiare tra macchine, perché privo di un’identità. Questi progetti sono elencati a parte come Progetti non mappati nella scheda Progetti.

Se uno stesso progetto dovesse comparire duplicato (per esempio dopo averlo registrato con nomi diversi), la scheda Sistema offre Riallinea progetti e memorie: riunisce le memorie sotto un’unica voce, così che ogni progetto compaia una sola volta. È sicuro da eseguire in qualsiasi momento e viene comunque lanciato in automatico dopo ogni sincronizzazione.

Riallinea progetti e memorie: utile se lo stesso progetto compare più di una volta.

La sincronizzazione “non parte” / stato passivo

Sintomo: la barra di stato mostra lo stato passivo (nessun indicatore colorato) e la sincronizzazione non avviene, anche dopo aver premuto Sincronizza ora.

Causa: un’altra finestra di VS Code sullo stesso computer possiede l’engine di sincronizzazione. Con più finestre VS Code aperte, una sola guida la sync; le altre seguono in modalità passiva. È un comportamento normale.

Soluzione:

1. Individua l’altra finestra VS Code aperta (anche in background) e usala per avviare la sincronizzazione, oppure chiudila.
2. Chiuse le finestre aggiuntive, l’engine viene acquisito automaticamente dalla finestra rimasta.
3. In caso di dubbi, usa Controllo sistema nella scheda Sistema per una diagnostica completa dell’ambiente.

Il Controllo sistema verifica l’ambiente e segnala cosa va e cosa no (i valori mostrati sono d’esempio).

Limite di posti (seat) raggiunto

Sintomo: al tentativo di attivare l’estensione su una nuova macchina compare Limite macchine raggiunto o la macchina non viene registrata.

Causa: il numero di macchine attive ha raggiunto il limite della tua edizione.

Soluzione:

1. Apri la dashboard su una macchina già attiva, scheda Macchine.
2. Identifica le macchine inutilizzate o ferme (l’interfaccia segnala quelle ferme da 30+ giorni).
3. Premi Disattiva sulla macchina da rilasciare (nell’edizione Team serve il ruolo Maintainer).
4. Torna alla nuova macchina e ripeti l’attivazione.

In alternativa, valuta un aggiornamento a un’edizione con più posti o illimitata.

Credenziali MCP mancanti dopo la sincronizzazione

Sintomo: dopo un pull su una nuova macchina, i server MCP compaiono nella configurazione ma non funzionano; Claude Code segnala credenziali mancanti o non valide.

Causa: le credenziali dei server MCP vengono rimosse prima del push (scrubbing) per sicurezza. Nel repository viaggia solo la struttura del server (URL, nome, argomenti).

Soluzione:

1. Apri VS Code sulla nuova macchina e vai alle impostazioni MCP (o al file di configurazione indicato dall’app).
2. Reinserisci le credenziali (token, chiave API…) per ogni server MCP che le richiede.
3. Le credenziali finiscono nel secret store di VS Code — non è necessario ripeterle ad ogni sincronizzazione futura su questa macchina.

Comandi o azioni che restano in attesa

Sintomo: un pulsante d’azione della dashboard mostra uno spinner e sembra “bloccato”.

Causa: ogni pulsante si disabilita con uno spinner finché l’operazione non risponde. È il comportamento atteso, non un blocco.

Soluzione: attendi il completamento dell’operazione. Non ripetere il click: lanciare di nuovo la stessa azione non la accelera.