9. Aiuto
9.1 Quando qualcosa non va
Su un PC nuovo, prima la «Salute del kit». Poi i problemi più comuni, il messaggio che vedi e che cosa fare: download, porte occupate, server che non partono, accessi scaduti. E come segnalare un problema con lo zip della diagnostica.
In breve
- Cerca il messaggio che vedi nella casella qui sotto: la guida ne raccoglie i più comuni, con il rimedio.
- Quasi ogni errore ha un suggerimento al passaggio del mouse e una riga di output o di log che dice di più.
- Il log dell'app è in data\app\logs\app.log; quelli dei server accanto.
Salute del kit
Su un PC nuovo, o con il kit su un'altra chiavetta, guarda prima Impostazioni › «Il kit» › «Salute del kit»: una riga per controllo, verde se va bene, gialla per un avviso, rossa per un errore, e sotto che cosa fare. «Controlla di nuovo» rifà i controlli dopo una correzione.
- Il disco. FAT32 tiene file fino a 4 GB (niente modelli locali né copie di database grandi) e niente collegamenti: per un kit su chiavetta è meglio exFAT, o NTFS se resta su Windows. Su macOS e Linux un disco montato noexec (o FAT32 con showexec su Linux) non lascia partire i programmi: la riga dà il comando per rimontarlo.
- Lo spazio libero: sotto 5 GB un avviso, sotto 1 GB un errore (installazioni, download e copie dei database non riescono). Libera spazio o sposta il kit su un disco più grande.
- Il percorso del kit: &, %, !, ^, apici e lettere accentate o fuori dall'alfabeto latino confondono cmd, PowerShell, Maven e Gradle. Sposta il kit in una cartella con solo lettere, cifre, trattini e spazi.
- File resi privati da un altro account, spesso su un altro PC: il kit non li legge (impostazioni, chiavi, accessi degli agenti). La riga dà il comando per riprenderli, da eseguire in un terminale da amministratore: takeown e icacls su Windows, sudo chown su macOS e Linux. L'app non lo esegue da sé perché servono i diritti di amministratore.
- Su Linux, le librerie del sistema: libaio e libnuma per MySQL, libicu per .NET, libvulkan1 per la scheda video dei modelli locali (senza, restano sulla CPU). La riga dà il comando per installarle, per esempio con apt.
- Dalla riga di comando gli stessi controlli li fa
.\Atollo.exe check --kit | Out-Host, che finisce con 1 se uno è un errore.
Download e installazione
Un componente resta in «errore» con «non riuscito» e un messaggio di rete o di certificato.
Spesso è la rete: un proxy aziendale o l'ispezione HTTPS. Compila Impostazioni › Rete e riprova. Se non basta, usa il riquadro «Scaricalo dal browser» sotto la riga e consegna il file al kit.
Approfondisci: Rete aziendale: proxy, certificati, rete locale (6.3)
«in uso: chiudi i programmi del kit e riprova»
Un programma del kit (un progetto avviato, una console, l'editor, un database) sta usando i file da sostituire. Fermalo, chiudi le console e riprova. Se non sai che cosa è aperto, la pagina «Rimuovi l'unità» lo elenca.
Approfondisci: Rimuovere l'unità in sicurezza (7.1)
«C'è già un'installazione in corso.» oppure «Un'installazione è già in corso»
Aspetta che finisca (la barra di stato mostra il passo) o premi «Annulla» nella barra «Applica».
Un componente è «da aggiornare» (triangolo giallo).
Su macOS e Linux, dopo uno spostamento del kit, alcuni componenti vanno reinstallati: il kit lo fa da solo all'avvio. Se resta così, premi «Aggiorna tutto» in fondo alla pagina Strumenti.
Approfondisci: Su un altro PC, un'altra lettera, un'altra cartella (7.2)
Un programma si chiude da solo o manca una libreria, con il kit su una chiavetta.
Un file del programma può essersi danneggiato sulla chiavetta. Premi «Verifica i file» nella pagina Strumenti (o esegui check --files): elenca le cartelle con file mancanti o cambiati dall'installazione, e «Reinstalla» le rimette alla stessa versione, senza toccare progetti e database.
Approfondisci: La pagina Strumenti (5.1)
Progetti e siti
«Porta già assegnata a …», «La porta … è già del server/database/progetto …: scegline un'altra.», «Le porte da 7000 a 7099 sono dell'editor» o un programma che dice che la porta è occupata.
Una porta è di una cosa sola: un'azione di un progetto, un pool della pagina Server Web, una versione di un database o l'editor (7000-7099). Il messaggio dice chi ce l'ha già: «Porta già assegnata a …» un'altra azione, «già del server …» un pool, «già del database …» una versione di MySQL o MongoDB, «già del progetto …» un'azione. Vale per la porta di un'azione, di un pool e di una versione del database. Se invece la porta è di un programma del PC, lo dice quel programma. Per un'azione svuota il campo «Porta» per tornare alla porta automatica; altrimenti scegline un'altra tra 1024 e 65535.
Approfondisci: Avviare un progetto: azioni e porte (2.3)
Un'azione si ferma subito con «errore (codice 1)».
Leggi le ultime righe dell'output: di solito dicono che cosa manca. Casi frequenti: dipendenze non installate (esegui prima npm install o composer install), un componente mancante (sezione «Componenti» › «Installa ciò che manca»), una versione sbagliata (sezione «Versioni»).
Approfondisci: Componenti e versioni di un progetto (2.4)
«Azione non trovata: premi Aggiorna»
Il progetto è cambiato (per esempio panel.json). Premi «Aggiorna» nella pagina del progetto.
«panel.json non è un JSON valido: ignorato.»
C'è un errore di sintassi nel file (una virgola in più, una virgoletta mancante). Correggilo nell'editor e premi «Aggiorna».
Approfondisci: Avviare un progetto: azioni e porte (2.3)
«Il server condiviso … non è partito: guarda la pagina Server Web.»
Apri la pagina Server Web, scegli il pool e guarda l'errore. Spesso la porta è occupata: cambia porta al profilo, oppure scegli «Server tutto suo» nella sezione «Sito web» del progetto.
Approfondisci: Siti web e indirizzi .localhost (3.3)
Il sito si apre ma mostra file vecchi o una pagina bianca.
Controlla la cartella in «Servi come sito web la cartella» (per molti framework PHP è public) e ricarica la pagina del browser ignorando la cache (Ctrl+F5).
L'editor non si accorge dei file cambiati.
Su Windows succede se una cartella del percorso del kit inizia con una cifra, con x o con u: l'app lo segnala con un avviso. Sposta il kit in un percorso diverso.
Approfondisci: Il primo avvio (1.2)
Database
«La porta … è già usata da un altro programma: cambiala qui sotto.»
Sul PC gira un altro MySQL o MongoDB (installato a parte) sulla stessa porta. Cambia la «Porta» nella pagina del server (per esempio 3307) e avvialo di nuovo; poi riscrivi la connessione nel .env dei progetti con «Scrivi in .env».
Approfondisci: I server di database (3.1)
Il server resta in «Errore» dopo l'avvio.
La pagina del server mostra l'ultimo errore e il percorso del log (data\app\logs). Su Linux MySQL può chiedere le librerie libaio e libnuma: il messaggio dice il comando per installarle.
Il progetto non si collega al database.
Controlla che il server sia «Avviato», poi usa «Scrivi in .env» nella sezione «Database» del progetto: il .env avrà utente, password e porta giusti. Se il progetto usa un'altra versione del server, la porta è diversa (3307…).
Approfondisci: Il database di un progetto (3.2)
Agenti, Git e GitHub
«accesso scaduto» negli agenti.
Apri l'agente in un progetto: rinnova l'accesso, o te lo fa rifare.
Approfondisci: Gli agenti: Claude Code, Codex, Antigravity, Pi (4.1)
Git dice «Please tell me who you are» al primo commit.
Scrivi nome ed e-mail in Impostazioni › «Account GitHub» › «Chi firma i commit», oppure accedi a GitHub: se sono vuoti, li riempie l'account. In un terminale del kit funziona anche git config --global user.name e user.email.
Approfondisci: L'account GitHub del kit (6.1)
«GitHub ha rifiutato l'accesso: accedi di nuovo.»
Il token non è più valido (revocato o scaduto). In Impostazioni › «Account GitHub» premi «Esci» e poi «Accedi a GitHub».
Approfondisci: L'account GitHub del kit (6.1)
Avvio dell'app
«Il disco del kit è in sola lettura: impossibile scrivere nella cartella …»
La chiavetta è protetta da scrittura (a volte c'è un interruttore) o montata in sola lettura. Il kit deve poter scrivere nella sua cartella.
macOS: «macOS ha aperto Atollo da una copia temporanea in sola lettura (App Translocation)».
Succede con le app scaricate e non autenticate. Il messaggio mostra un comando xattr: eseguilo nel Terminale e riapri Atollo.
Approfondisci: Su un altro PC, un'altra lettera, un'altra cartella (7.2)
Linux: il disco è montato con noexec, o manca WebKitGTK.
Il messaggio spiega che cosa fare: rimonta il disco con il permesso di esecuzione, o installa i pacchetti indicati.
Windows: manca WebView2.
WebView2 è il componente di Windows che disegna la finestra; c'è già in Windows 11 e quasi sempre in Windows 10. Se manca, Atollo mostra il collegamento per installarlo.
Avviso: «Su questo PC sono aperti programmi di un'altra copia del kit».
Solo un'informazione: un altro kit è aperto. Le due copie non condividono niente.
Se il problema non è qui
- Leggi l'output dell'azione (sezione «Avvio») o il log del server: l'ultima riga di solito dice la causa.
- Chiudi Atollo e riaprilo: molte cose (ambiente, agenti, file del kit) vengono rigenerate a ogni avvio.
- Controlla i componenti con «Verifica» nella pagina Strumenti, o con
.\Atollo.exe check | Out-Host. - Se ancora non va, segnalalo: la sezione qui sotto dice come.
Segnalare un problema
In Impostazioni › «Il kit» › «Segnalare un problema» ci sono due pulsanti, da usare in quest'ordine.
- «Esporta diagnostica» crea sul PC lo zip atollo-diagnostica-<data-ora>.zip in data\app\diagnostics: versione e sistema, disco del kit (file system, tipo, spazio libero), RAM, ambiente del kit, la verifica dei programmi, i componenti, le porte e la parte finale di ogni log. «Apri la cartella» lo mostra. Dalla riga di comando fa lo stesso
.\Atollo.exe diagnostics | Out-Host. - Prima di scrivere lo zip, ogni segreto che il kit conserva (le chiavi di data\app\secrets, il token di Claude Code, le password dei database, gli accessi degli agenti, il token di GitHub) diventa *** ovunque compaia; la cartella del tuo profilo diventa ~, il tuo nome utente e il nome del PC ***. Aprilo e guardalo comunque prima di allegarlo: un progetto può scrivere nei log cose che il kit non conosce.
- «Segnala un problema» apre nel browser una segnalazione nuova su github.com/nabre/atollo con il modulo dei problemi: versione di Atollo e sistema (kit, build di Windows, file system e tipo del disco) sono già scritti. Racconta che cosa è successo e i passi per rifarlo, e trascina lo zip nella segnalazione.
- L'app non manda niente: lo zip resta sul PC finché non lo alleghi tu, e la segnalazione arriva a GitHub solo quando premi «Create» (serve un account GitHub). Da lì valgono le regole sulla privacy di GitHub, e la segnalazione è pubblica.