Problèmes CLI

Vos identifiants stockés sont manquants ou le jeton de rafraîchissement n'est plus valide.

Correctif : Exécutez jamdesk login pour démarrer une nouvelle session. Cela remplace tout ce qui était dans ~/.jamdeskrc.

Si l'erreur revient immédiatement après la connexion, vérifiez que ~/.jamdeskrc a bien été écrit :

cat ~/.jamdeskrc

Le fichier doit contenir un objet auth avec refreshToken, email et uid. S'il est vide ou manquant, votre répertoire personnel peut avoir des problèmes de permissions.

Le CLI démarre un serveur local sur le port 9876 pour recevoir le callback d'authentification de votre navigateur. Si le callback n'arrive jamais, la connexion expire après 2 minutes.

Causes fréquentes :

• Un pare-feu bloque le serveur local
• L'onglet du navigateur a été fermé avant la fin de l'authentification
• Le port 9876 est occupé (le CLI choisit automatiquement un autre port, mais l'URL doit correspondre)

Correctif : Copiez l'URL affichée dans le terminal et ouvrez-la manuellement. Vérifiez que le numéro de port dans l'URL correspond à celui sur lequel le CLI écoute.

Comportement normal dans les environnements sans interface graphique (sessions SSH, conteneurs Docker, runners CI). L'URL de connexion est toujours affichée dans le terminal, même quand aucun navigateur n'est disponible.

Copiez-la et ouvrez-la dans n'importe quel navigateur pouvant atteindre votre machine sur le port de callback.

Changer votre mot de passe Jamdesk invalide tous les jetons de rafraîchissement existants. Le CLI détecte cela (TOKEN_EXPIRED ou INVALID_REFRESH_TOKEN) et efface automatiquement l'authentification stockée.

Exécutez jamdesk login à nouveau.

Un seul build s'exécute à la fois par projet. Le CLI renvoie cette erreur (code BUILD_IN_PROGRESS) quand un build est en file d'attente ou en cours d'exécution.

Correctif : Attendez que le build actuel se termine. Vérifiez l'état dans Deployments du dashboard. Si un build semble bloqué, demandez au propriétaire du projet de vérifier le dashboard.

Pas de docs.json dans le répertoire courant, ou il contient des erreurs de syntaxe JSON.

Correctif :

1. Assurez-vous d'être dans le bon répertoire : ls docs.json
2. Exécutez jamdesk validate pour des détails d'erreur spécifiques
3. Vérifiez les virgules manquantes, les crochets non fermés ou les virgules de fin (le CLI utilise JSON, pas JSON5 pour docs.json)

Votre archive compressée dépasse la limite de 100 Mo. Tout ce qui n'est pas exclu par .gitignore ou la liste d'exclusion intégrée est empaqueté.

Correctif : Vérifiez ce qui est inclus. Causes fréquentes : fichiers vidéo, gros PDF, images non compressées, exports de données. Ajoutez-les à .gitignore.

Toujours exclus quelle que soit la configuration de .gitignore : .git, node_modules, .next, .env*, *.pem, *.key, credentials.json, .DS_Store.

Chaque fichier correspond à un motif d'exclusion. Il ne reste rien à uploader.

Correctif : Vérifiez votre .gitignore. S'il bloque des fichiers MDX ou docs.json, le CLI n'a rien sur quoi travailler.

Soit le projectId dans docs.json ne correspond à aucun projet de votre compte, soit vous n'êtes pas membre de ce projet.

Correctif :

• Supprimez le champ projectId de docs.json et relancez jamdesk deploy pour choisir un nouveau projet
• Vérifiez que vous êtes connecté avec le bon compte : jamdesk whoami
• Vérifiez l'appartenance au projet dans le dashboard

L'état du build est interrogé toutes les 2 secondes. Si votre réseau est instable, jusqu'à 3 échecs de polling consécutifs sont tolérés avant que le CLI abandonne.

Correctif : Appuyez sur Ctrl+C. Le build continue de s'exécuter en arrière-plan. Vérifiez l'état dans le dashboard. Un lien est affiché quand vous quittez.

L'upload a réussi, mais le build lui-même a échoué. Vous verrez l'erreur du service de build dans votre terminal.

Correctif : Vérifiez le journal de build dans le dashboard sous Deployments. Causes fréquentes : erreurs de syntaxe MDX, pages manquantes référencées dans la navigation, specs OpenAPI invalides. Exécutez jamdesk validate localement pour détecter ces problèmes avant de déployer.

Vous verrez un avertissement quand des fichiers ressemblent à des secrets (.env, *.pem, *.key, credentials.json, fichiers commençant par secret). Il s'agit d'un avertissement, pas d'un blocage.

Correctif : Ajoutez les fichiers à .gitignore pour les exclure des uploads. S'ils sont intentionnels (par exemple, des fichiers de clés d'exemple dans votre documentation), ignorez l'avertissement.

Plusieurs choses peuvent empêcher le démarrage.

Essayez dans l'ordre :

1. jamdesk doctor pour vérifier la version de Node.js (v20+ requise) et l'environnement
2. jamdesk clean pour effacer les dépendances en cache
3. jamdesk dev --verbose pour une sortie d'erreur détaillée
4. jamdesk dev --clean pour effacer le cache de build avant de démarrer

Le CLI essaie 10 ports consécutifs à partir du port demandé (par défaut 3000). Si les 10 sont occupés, il échoue.

Correctif :

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

# Pick a different port
jamdesk dev --port 3001

Pour définir un port par défaut permanent, ajoutez "defaultPort": 3001 à votre fichier ~/.jamdeskrc. N'écrasez pas le fichier — il peut contenir vos identifiants d'authentification.

Si le serveur de développement est tué en pleine compilation (fermeture forcée, crash système), le cache .next peut se corrompre. Vous verrez des erreurs "corrupted database" ou des erreurs de panique au prochain démarrage.

Correctif :

jamdesk dev --clean

Cela efface le répertoire .next et repart de zéro.

Le premier jamdesk dev installe les dépendances d'exécution dans ~/.jamdesk/node_modules. Cela se produit une seule fois et peut prendre 1 à 2 minutes sur des connexions plus lentes.

Les démarrages suivants ignorent l'installation sauf si la version du CLI change.

Si npm install se bloque lors du premier démarrage, il y a un délai d'expiration de 5 minutes.

Correctif :

1. Vérifiez votre connexion internet
2. jamdesk clean pour effacer les installations partielles
3. Réessayez
4. Si npm est constamment lent, vérifiez votre configuration de registre npm : npm config get registry

MDX traite < comme un ouvre-balise JSX. Écrire <50% provoque une erreur d'analyse.

Correctif : Échappez avec < ou reformulez. Exécutez jamdesk validate pour les numéros de ligne et les suggestions.

jamdesk broken-links a trouvé des liens internes pointant vers des pages qui n'existent pas.

Correctif : Vérifiez les chemins de fichiers. Erreurs fréquentes : mauvaise casse (Quickstart vs quickstart), inclusion de l'extension .mdx, ou anciens chemins qui ont été renommés.

Le CLI suggère des corrections pour les correspondances proches (à 3 caractères près d'une faute de frappe).

Le CLI valide les specs OpenAPI référencées dans docs.json. Les échecs incluent des références $ref invalides, des champs obligatoires manquants ou des erreurs de syntaxe.

Correctif : Exécutez jamdesk openapi-check path/to/spec.yaml pour une sortie détaillée. Utilisez l'éditeur Swagger pour déboguer les specs complexes.

Non installé globalement, ou votre shell ne trouve pas le binaire.

Correctif :

npm install -g jamdesk

Si vous avez installé avec curl, assurez-vous que ~/.jamdesk/bin est dans votre PATH.

L'accès en écriture est nécessaire pour ~/.jamdesk (cache) et ~/.jamdeskrc (identifiants).

Correctif :

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

jamdesk update encapsule npm install -g jamdesk@latest. Si npm a des problèmes de permissions ou que le registre est inaccessible, cela échoue.

Correctif : Mettez à jour manuellement :

npm install -g jamdesk@latest

Si cela échoue également, vérifiez npm config get registry et essayez sudo npm install -g jamdesk@latest.