Problemi CLI

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

Soluzione: esegui jamdesk login per avviare una nuova sessione. Questa operazione sostituisce il contenuto precedente di ~/.jamdeskrc.

Se l'errore si ripresenta subito dopo l'accesso, 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 directory home potrebbe presentare problemi di autorizzazioni.

La CLI avvia un server locale sulla porta 9876 per ricevere il callback di autenticazione dal browser. Se il callback non arriva, l'accesso scade dopo 2 minuti.

Cause comuni:

• Un firewall blocca il server locale
• La scheda del browser è stata chiusa prima del completamento dell'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 negli ambienti headless (sessioni SSH, container Docker, runner CI). L'URL di accesso viene sempre stampato nel terminale, anche quando non è disponibile alcun browser.

Copialo e aprilo in un browser in grado di raggiungere il tuo computer sulla porta di callback.

La modifica della password Jamdesk invalida tutti i token di aggiornamento esistenti. La CLI rileva questo problema (TOKEN_EXPIRED o INVALID_REFRESH_TOKEN) e cancella automaticamente le credenziali di autenticazione salvate.

Esegui nuovamente jamdesk login.

È possibile eseguire una sola build alla volta per progetto. La CLI restituisce questo errore (codice BUILD_IN_PROGRESS) quando una build è in coda o in esecuzione.

Soluzione: attendi il completamento della build corrente. Controlla lo stato in Deployments nel dashboard. Se una build sembra bloccata, chiedi al proprietario del progetto di controllare il dashboard.

Nella directory corrente non è presente docs.json, oppure il file contiene errori di sintassi JSON.

Soluzione:

1. Assicurati di trovarti nella directory corretta: ls docs.json
2. Esegui jamdesk validate per visualizzare i dettagli degli errori
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 nel pacchetto tutto ciò che non è escluso da .gitignore o dall'elenco di esclusione integrato.

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

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

Ogni file corrisponde a un modello di esclusione. Non è rimasto nulla da caricare.

Soluzione: controlla il tuo .gitignore. Se blocca i file MDX o docs.json, la CLI non ha nulla con cui lavorare.

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

Soluzione:

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

Lo stato della build viene verificato ogni 2 secondi. Se la rete è instabile, vengono tollerati fino a 3 errori consecutivi di polling prima che la CLI interrompa l'operazione.

Soluzione: premi Ctrl+C. La build continua a essere eseguita in background. Controlla lo stato nel dashboard. Quando esci viene stampato un link.

Il caricamento è riuscito, ma la build non è andata a buon fine. Nel terminale vedrai l'errore restituito dal servizio di build.

Soluzione: controlla il log della build nel dashboard, in Deployments. Cause comuni: errori di sintassi MDX, pagine mancanti a cui fa riferimento la navigazione, specifiche OpenAPI non valide. Esegui jamdesk validate localmente per rilevare questi problemi prima del deploy.

Viene visualizzato un avviso quando i file sembrano contenere segreti (.env, *.pem, *.key, credentials.json, file che iniziano con secret). Si tratta di un avviso, non di un blocco.

Soluzione: aggiungi i file a .gitignore per escluderli dai caricamenti. Se sono intenzionali (ad esempio file di chiavi di esempio nella documentazione), ignora l'avviso.

Diversi fattori possono impedire l'avvio.

Prova in quest'ordine:

1. jamdesk doctor per controllare la versione di Node.js (è richiesta la v20 o successiva) e l'ambiente
2. jamdesk clean per cancellare le dipendenze memorizzate nella cache
3. jamdesk dev --verbose per visualizzare un output dettagliato degli errori
4. jamdesk dev --clean per cancellare la cache della build prima dell'avvio

La CLI prova 10 porte consecutive a partire da quella richiesta (3000 per impostazione predefinita). Se tutte e 10 sono occupate, l'operazione non riesce.

Soluzione:

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

# Pick a different port
jamdesk dev --port 3001

Per impostare un valore predefinito permanente, aggiungi "defaultPort": 3001 al file ~/.jamdeskrc. Non sovrascrivere il file: potrebbe contenere le credenziali di autenticazione.

Se il server di sviluppo viene terminato durante la compilazione (chiusura forzata o arresto anomalo del sistema), la cache .next può danneggiarsi. Al successivo avvio visualizzerai errori relativi a un "database corrotto" o errori panic.

Soluzione:

jamdesk dev --clean

Questa operazione elimina la directory .next e avvia una nuova sessione.

La prima esecuzione di jamdesk dev installa le dipendenze runtime in ~/.jamdesk/node_modules. Questa operazione avviene una sola volta e può richiedere 1-2 minuti sulle connessioni più lente.

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

Se npm install si blocca durante la prima esecuzione, il timeout è di 5 minuti.

Soluzione:

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

MDX interpreta < come l'apertura di un tag JSX. Scrivere <50% causa un errore di analisi.

Soluzione: usa < oppure riscrivi il contenuto. Esegui jamdesk validate per visualizzare 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 o minuscole errate (Quickstart invece di quickstart), estensione .mdx inclusa oppure vecchi percorsi che sono stati rinominati.

La CLI suggerisce correzioni per le corrispondenze vicine (entro 3 caratteri da un errore di battitura).

Correggili automaticamente. Se un link non valido ha una destinazione corretta non ambigua (un'ancora con un errore di battitura o una differenza tra le ancore delle varie lingue), esegui jamdesk fix --dry-run per visualizzare in anteprima le modifiche, quindi jamdesk fix per applicarle. Riscrive solo i link la cui ancora corretta è un'intestazione reale nella pagina di destinazione; i casi ambigui devono essere corretti manualmente. Consulta Correzione automatica dei link non validi.

La CLI convalida le specifiche OpenAPI a cui fa riferimento 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 visualizzare un output dettagliato. Usa Swagger Editor per eseguire il debug di specifiche complesse.

Il comando non è installato globalmente oppure la shell non riesce a trovare il file binario.

Soluzione:

npm install -g jamdesk

Se hai eseguito l'installazione con curl, assicurati che ~/.jamdesk/bin sia incluso nel tuo PATH.

È necessario disporre dell'accesso in scrittura a ~/.jamdesk (cache) e ~/.jamdeskrc (credenziali).

Soluzione:

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

jamdesk update esegue npm install -g jamdesk@latest. Se npm presenta problemi di autorizzazione o il registro non è raggiungibile, l'operazione non riesce.

Soluzione: esegui manualmente l'aggiornamento:

npm install -g jamdesk@latest

Se anche questa operazione non riesce, controlla npm config get registry e prova sudo npm install -g jamdesk@latest.