Problèmes CLI

Vos identifiants stockés sont manquants ou le refresh token n'est plus valide.

Correction : Exécutez jamdesk login pour démarrer une nouvelle session. Cela remplace le contenu de ~/.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 absent, votre répertoire personnel a peut-être des problèmes de permissions.

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

Causes courantes :

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

Correction : 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.

Normal dans les environnements headless (sessions SSH, conteneurs Docker, runners CI). L'URL de connexion est toujours affichée dans le terminal, même si aucun navigateur n'est disponible.

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

Changer votre mot de passe Jamdesk invalide tous les refresh tokens existants. Le CLI détecte cela (TOKEN_EXPIRED ou INVALID_REFRESH_TOKEN) et efface automatiquement les identifiants stockés.

Exécutez à nouveau jamdesk login.

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

Correction : Attendez la fin du build en cours. Vérifiez le statut dans Deployments sur le dashboard. Si un build semble bloqué, demandez au propriétaire du projet de vérifier le dashboard.

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

Correction :

1. Assurez-vous d'être dans le bon répertoire : ls docs.json
2. Exécutez jamdesk validate pour des détails précis sur l'erreur
3. Vérifiez l'absence de virgules manquantes, de crochets non fermés, ou de 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é.

Correction : Vérifiez ce qui est inclus. Coupables courants : fichiers vidéo, PDF volumineux, images non compressées, exports de données. Ajoutez-les à .gitignore.

Toujours exclus, quel que soit .gitignore : .git, node_modules, .next, .env*, *.pem, *.key, credentials.json, .DS_Store.

Chaque fichier correspondait à un motif d'exclusion. Il ne reste rien à envoyer.

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

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

Correction :

• 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

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

Correction : Appuyez sur Ctrl+C. Le build continue de s'exécuter en arrière-plan. Vérifiez le statut dans le dashboard. Un lien est affiché lorsque 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.

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

Vous verrez un avertissement lorsque des fichiers ressemblent à des secrets (.env, *.pem, *.key, credentials.json, fichiers commençant par secret). C'est un avertissement, pas un blocage.

Correction : 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 éléments peuvent empêcher le démarrage.

À essayer 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 mises 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 le démarrage

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

Correction :

# 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 arrêté en pleine compilation (arrêt forcé, plantage système), le cache .next peut se corrompre. Vous verrez des erreurs "corrupted database" ou des erreurs panic au prochain démarrage.

Correction :

jamdesk dev --clean

Cela efface le répertoire .next et redémarre à zéro.

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

Les lancements suivants sautent l'installation, sauf si la version du CLI change.

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

Correction :

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 la configuration de votre registre npm : npm config get registry

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

Correction : Échappez avec < ou réécrivez. Exécutez jamdesk validate pour obtenir les numéros de ligne et des suggestions.

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

Correction : Vérifiez les chemins de fichiers. Erreurs courantes : casse incorrecte (Quickstart vs quickstart), inclusion de l'extension .mdx, ou anciens chemins renommés.

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

Corrigez-les automatiquement. Si un lien cassé a une cible correcte non ambiguë (une ancre mal orthographiée ou une dérive d'ancre inter-locale), exécutez jamdesk fix --dry-run pour prévisualiser les changements, puis jamdesk fix pour les appliquer. Il ne réécrit que les liens dont l'ancre corrigée est un titre réel sur la page cible ; les cas ambigus restent à corriger manuellement. Voir Correction automatique des liens cassés.

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

Correction : Exécutez jamdesk openapi-check path/to/spec.yaml pour une sortie détaillée. Utilisez le Swagger Editor pour déboguer les spécifications complexes.

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

Correction :

npm install -g jamdesk

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

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

Correction :

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 injoignable, cela échoue.

Correction : 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.