Problemi CLI

Le credenziali salvate mancano oppure il refresh token non è più valido.

Soluzione: Esegui jamdesk login per avviare una nuova sessione. Questo sostituisce il contenuto di ~/.jamdeskrc.

Se l'errore continua a comparire subito dopo il login, verifica che ~/.jamdeskrc sia stato scritto:

cat ~/.jamdeskrc

Il file dovrebbe contenere un oggetto auth con refreshToken, email e uid. Se è vuoto o manca, la tua directory home potrebbe avere problemi di permessi.

La CLI avvia un server locale sulla porta 9876 per ricevere il callback di autenticazione dal browser. Il login va in timeout se il callback non arriva entro 2 minuti.

Cause comuni:

• Un firewall blocca il server locale
• La scheda del browser è stata chiusa prima di completare l'autenticazione
• La porta 9876 è occupata (la CLI sceglie automaticamente un'altra porta, ma l'URL deve corrispondere)

Soluzione: Copia l'URL stampato nel terminale e aprilo manualmente. Verifica che il numero di porta nell'URL corrisponda a quello su cui la CLI è in ascolto.

È normale in ambienti headless (sessioni SSH, container Docker, runner CI). La CLI stampa sempre l'URL di login nel terminale.

Copialo e aprilo in un browser che possa raggiungere la tua macchina sulla porta di callback.

Cambiare la password di Jamdesk invalida tutti i refresh token esistenti. La CLI lo rileva (TOKEN_EXPIRED o INVALID_REFRESH_TOKEN) e cancella automaticamente l'autenticazione salvata.

Esegui di nuovo jamdesk login.

Per progetto viene eseguita una sola build alla volta. La CLI restituisce questo errore (codice BUILD_IN_PROGRESS) quando una build è in coda o in esecuzione.

Soluzione: Attendi il completamento della build in corso. Controlla Deployments nella dashboard per lo stato. Se una build sembra bloccata, chiedi al proprietario del progetto di verificarla nella dashboard.

Nella directory corrente non c'è alcun docs.json, oppure contiene errori di sintassi JSON.

Soluzione:

1. Verifica di essere nella directory giusta: ls docs.json
2. Esegui jamdesk validate per i dettagli specifici dell'errore
3. Controlla la presenza di virgole mancanti, parentesi non chiuse o virgole finali (la CLI usa JSON, non JSON5, per docs.json)

Il tuo tarball compresso supera il limite di 100 MB. Viene incluso tutto ciò che non è escluso da .gitignore o dall'elenco di esclusioni integrato.

Soluzione: Controlla cosa viene incluso. Cause comuni: file video, PDF di grandi dimensioni, immagini non compresse, dump di dati. Aggiungili a .gitignore.

Sempre esclusi indipendentemente da .gitignore: .git, node_modules, .next, .env*, *.pem, *.key, credentials.json, .DS_Store.

Tutti i file corrispondono a un pattern di esclusione.

Soluzione: Verifica che il tuo .gitignore non escluda i file MDX o docs.json.

Il projectId in docs.json non corrisponde ad alcun progetto del tuo account, oppure non sei membro di quel progetto.

Soluzione:

• Rimuovi il campo projectId da docs.json ed esegui di nuovo jamdesk deploy per scegliere un nuovo progetto
• Verifica di aver effettuato l'accesso con l'account corretto: jamdesk whoami
• Controlla l'appartenenza al progetto nella dashboard

La CLI controlla lo stato della build ogni 2 secondi. Si arrende dopo 3 errori consecutivi di polling.

Soluzione: Premi Ctrl+C. La build continua a essere eseguita in background. Controlla lo stato nella dashboard. La CLI stampa un link quando esci.

L'upload è riuscito, ma la build è fallita. Il terminale mostra l'errore del servizio di build.

Soluzione: Controlla il log della build nella dashboard sotto Deployments. Cause comuni: errori di sintassi MDX, pagine mancanti referenziate nella navigazione, specifiche OpenAPI non valide. Esegui jamdesk validate in locale per individuarle prima del deploy.

La CLI avvisa dei file che sembrano segreti (.env, *.pem, *.key, credentials.json, file che iniziano con secret). L'avviso non blocca il deploy.

Soluzione: Aggiungi i file a .gitignore per escluderli dagli upload. Se sono intenzionali (ad esempio file di chiavi di esempio nella tua documentazione), ignora l'avviso.

Prova in quest'ordine:

1. jamdesk doctor per controllare la versione di Node.js (richiesta 22.18+ o 24.11+) e l'ambiente
2. jamdesk clean per cancellare le dipendenze in cache
3. jamdesk dev --verbose per un output dettagliato degli errori
4. jamdesk dev --clean per cancellare la cache di build prima dell'avvio

jamdesk si interrompe con "jamdesk requires Node.js 22.18+ or 24.11+" su qualsiasi altra versione, incluso Node.js 23. Aggiorna prima Node.js, poi la CLI.

jamdesk dev esegue l'anteprima da ~/.jamdesk usando il node che compare per primo nel tuo PATH. Se un version manager come Volta, asdf o mise fissa una versione più recente di Node.js solo per la cartella del progetto, l'anteprima continua a usare il Node.js predefinito. jamdesk doctor lo segnala come "first on PATH, used by jamdesk dev", e jamdesk dev mostra l'avviso "The node first on your PATH is …".

Soluzione: Installa una versione supportata di Node.js e impostala come predefinita, non solo per il progetto. Con nvm, esegui nvm install 24 e poi nvm alias default 24 (su Windows con nvm-windows, nvm install 24 e poi nvm use 24). Apri un nuovo terminale nella tua cartella home e verifica che node --version mostri 22.18+ o 24.11+.

La CLI prova 10 porte consecutive a partire da quella richiesta (default 3000). Se tutte e 10 sono occupate, fallisce.

Soluzione:

# Find what's using the port
lsof -i :3000

# Pick a different port
jamdesk dev --port 3001

Imposta un default permanente aggiungendo "defaultPort": 3001 al tuo file ~/.jamdeskrc. Non sovrascrivere il file: potrebbe contenere le tue credenziali di autenticazione.

Interrompere il server di sviluppo durante la compilazione (force quit, crash di sistema) può corrompere la cache .next. Al successivo avvio compaiono errori "corrupted database" o panic.

Soluzione:

jamdesk dev --clean

Questo cancella la directory .next e avvia da zero.

Il primo jamdesk dev installa le dipendenze di runtime in ~/.jamdesk/node_modules. Accade una sola volta e può richiedere 1-2 minuti con connessioni lente.

Le esecuzioni successive saltano l'installazione, a meno che non cambi la versione della CLI.

npm install alla prima esecuzione va in timeout dopo 5 minuti.

Soluzione:

1. Controlla la tua connessione internet
2. jamdesk clean per cancellare le installazioni parziali
3. Riprova
4. Se npm è costantemente lento, controlla la configurazione del registry npm: npm config get registry

MDX interpreta < come apertura di un tag JSX. Scrivere <50% causa un errore di parsing.

Soluzione: Escapa con < oppure riscrivi. Esegui jamdesk validate per i numeri di riga e i suggerimenti.

jamdesk broken-links ha trovato link interni che puntano a pagine inesistenti.

Soluzione: Controlla i percorsi dei file. Errori comuni: maiuscole/minuscole sbagliate (Quickstart invece di quickstart), estensione .mdx inclusa, oppure vecchi percorsi rinominati.

La CLI suggerisce correzioni per corrispondenze simili (entro 3 caratteri da un refuso).

Correggili automaticamente. Se un link rotto ha un obiettivo corretto e univoco (un'ancora con refuso o uno scostamento di ancora tra lingue), esegui jamdesk fix --dry-run per vedere in anteprima le modifiche, poi jamdesk fix per applicarle. Riscrive solo i link la cui ancora corretta corrisponde a un titolo reale nella pagina di destinazione. Correggi a mano i casi ambigui. Vedi Correzione automatica dei link rotti.

La CLI valida le specifiche OpenAPI referenziate in docs.json. Gli errori includono riferimenti $ref non validi, campi obbligatori mancanti o errori di sintassi.

Soluzione: Esegui jamdesk openapi-check path/to/spec.yaml per un output dettagliato. Usa lo Swagger Editor per il debug di specifiche complesse.

Non installato globalmente, oppure la shell non riesce a trovare il binario.

Soluzione:

npm install -g jamdesk

Se hai installato con curl, assicurati che ~/.jamdesk/bin sia nel tuo PATH.

La CLI ha bisogno di permessi di scrittura su ~/.jamdesk (cache) e ~/.jamdeskrc (credenziali).

Soluzione:

ls -la ~/.jamdesk ~/.jamdeskrc
sudo chown -R $(whoami) ~/.jamdesk ~/.jamdeskrc

jamdesk update esegue npm install -g jamdesk@latest. Fallisce quando npm ha problemi di permessi o il registry non è raggiungibile.

Soluzione: Aggiorna manualmente:

npm install -g jamdesk@latest

Se fallisce anche questo, controlla npm config get registry e prova sudo npm install -g jamdesk@latest.