CLI-Probleme

Ihre gespeicherten Zugangsdaten fehlen oder das Refresh-Token ist nicht mehr gültig.

Lösung: Führen Sie jamdesk login aus, um eine neue Sitzung zu starten. Dies ersetzt den bisherigen Inhalt von ~/.jamdeskrc.

Falls der Fehler nach der Anmeldung sofort erneut auftritt, prüfen Sie, ob ~/.jamdeskrc geschrieben wurde:

cat ~/.jamdeskrc

Die Datei sollte ein auth-Objekt mit refreshToken, email und uid enthalten. Ist sie leer oder fehlt sie, gibt es möglicherweise Berechtigungsprobleme in Ihrem Home-Verzeichnis.

Die CLI startet einen lokalen Server auf Port 9876, um den Authentifizierungs-Callback aus Ihrem Browser zu empfangen. Die Anmeldung läuft in ein Timeout, wenn der Callback nicht innerhalb von 2 Minuten eintrifft.

Häufige Ursachen:

• Eine Firewall blockiert den lokalen Server
• Der Browser-Tab wurde vor Abschluss der Authentifizierung geschlossen
• Port 9876 ist belegt (die CLI wählt automatisch einen anderen Port, die URL muss jedoch passen)

Lösung: Kopieren Sie die im Terminal ausgegebene URL und öffnen Sie sie manuell. Prüfen Sie, ob die Portnummer in der URL mit dem Port übereinstimmt, auf dem die CLI lauscht.

Das ist in Umgebungen ohne Benutzeroberfläche normal (SSH-Sitzungen, Docker-Container, CI-Runner). Die CLI gibt die Anmelde-URL immer im Terminal aus.

Kopieren Sie diese und öffnen Sie sie in einem beliebigen Browser, der Ihren Rechner über den Callback-Port erreichen kann.

Wenn Sie Ihr Jamdesk-Passwort ändern, werden alle bestehenden Refresh-Tokens ungültig. Die CLI erkennt dies (TOKEN_EXPIRED oder INVALID_REFRESH_TOKEN) und löscht die gespeicherte Authentifizierung automatisch.

Führen Sie jamdesk login erneut aus.

Pro Projekt läuft jeweils nur ein Build. Die CLI gibt diesen Fehler (Code BUILD_IN_PROGRESS) zurück, wenn ein Build in der Warteschlange steht oder läuft.

Lösung: Warten Sie, bis der aktuelle Build abgeschlossen ist. Den Status finden Sie im Dashboard unter Deployments. Wenn ein Build festzuhängen scheint, bitten Sie den Projektinhaber, im Dashboard nachzusehen.

Im aktuellen Verzeichnis gibt es keine docs.json oder sie enthält JSON-Syntaxfehler.

Lösung:

1. Stellen Sie sicher, dass Sie im richtigen Verzeichnis sind: ls docs.json
2. Führen Sie jamdesk validate aus, um genaue Fehlerdetails zu erhalten
3. Prüfen Sie auf fehlende Kommas, nicht geschlossene Klammern oder überflüssige Kommas (die CLI verwendet für docs.json JSON, nicht JSON5)

Ihr komprimiertes Tarball überschreitet das Limit von 100 MB. Alles, was nicht durch .gitignore oder die integrierte Ausschlussliste ausgeschlossen ist, wird gepackt.

Lösung: Prüfen Sie, was eingeschlossen wird. Typische Verursacher: Videodateien, große PDFs, unkomprimierte Bilder, Datenexporte. Fügen Sie sie zu .gitignore hinzu.

Immer ausgeschlossen, unabhängig von .gitignore: .git, node_modules, .next, .env*, *.pem, *.key, credentials.json, .DS_Store.

Alle Dateien wurden von einem Ausschlussmuster erfasst.

Lösung: Prüfen Sie, ob Ihre .gitignore keine MDX-Dateien oder docs.json ausschließt.

Entweder stimmt die projectId in docs.json mit keinem Projekt in Ihrem Konto überein, oder Sie sind kein Mitglied dieses Projekts.

Lösung:

• Entfernen Sie das Feld projectId aus docs.json und führen Sie jamdesk deploy erneut aus, um ein neues Projekt auszuwählen
• Prüfen Sie, ob Sie mit dem richtigen Konto angemeldet sind: jamdesk whoami
• Prüfen Sie die Projektmitgliedschaft im Dashboard

Die CLI fragt den Build-Status alle 2 Sekunden ab. Nach 3 aufeinanderfolgenden fehlgeschlagenen Abfragen gibt sie auf.

Lösung: Drücken Sie Strg+C. Der Build läuft im Hintergrund weiter. Prüfen Sie den Status im Dashboard. Beim Beenden gibt die CLI einen Link aus.

Der Upload war erfolgreich, der Build ist fehlgeschlagen. Das Terminal zeigt den Fehler des Build-Dienstes an.

Lösung: Prüfen Sie das Build-Protokoll im Dashboard unter Deployments. Häufige Ursachen: MDX-Syntaxfehler, in der Navigation referenzierte, aber fehlende Seiten, ungültige OpenAPI-Spezifikationen. Führen Sie jamdesk validate lokal aus, um diese Fehler vor dem Deploy zu finden.

Die CLI warnt vor Dateien, die wie Secrets aussehen (.env, *.pem, *.key, credentials.json, Dateien, deren Name mit secret beginnt). Die Warnung blockiert den Deploy nicht.

Lösung: Fügen Sie die Dateien zu .gitignore hinzu, um sie vom Upload auszuschließen. Sind sie beabsichtigt (z. B. Beispiel-Schlüsseldateien in Ihrer Dokumentation), können Sie die Warnung ignorieren.

In dieser Reihenfolge versuchen:

1. jamdesk doctor, um die Node.js-Version (22.18+ oder 24.11+ erforderlich) und die Umgebung zu prüfen
2. jamdesk clean, um zwischengespeicherte Abhängigkeiten zu löschen
3. jamdesk dev --verbose für detaillierte Fehlerausgaben
4. jamdesk dev --clean, um den Build-Cache vor dem Start zu leeren

jamdesk bricht mit „jamdesk requires Node.js 22.18+ or 24.11+“ bei jeder anderen Version ab, auch bei Node.js 23. Aktualisieren Sie zuerst Node.js, dann die CLI.

jamdesk dev führt die Vorschau aus ~/.jamdesk mit dem ersten node in Ihrem PATH aus. Wenn ein Versionsmanager wie Volta, asdf oder mise eine neuere Node.js-Version nur für Ihren Projektordner festlegt, läuft die Vorschau trotzdem mit Ihrer Standard-Node.js-Version. jamdesk doctor meldet dies als „first on PATH, used by jamdesk dev“, und jamdesk dev warnt: „The node first on your PATH is …“.

Lösung: Installieren Sie eine unterstützte Node.js-Version und machen Sie sie zu Ihrem Standard, nicht nur für Ihr Projekt. Mit nvm führen Sie nvm install 24 und danach nvm alias default 24 aus (unter Windows mit nvm-windows nvm install 24 und danach nvm use 24). Öffnen Sie ein neues Terminal in Ihrem Home-Verzeichnis und prüfen Sie, ob node --version 22.18+ oder 24.11+ anzeigt.

Die CLI versucht 10 aufeinanderfolgende Ports, beginnend mit dem angeforderten Port (Standard 3000). Sind alle 10 belegt, schlägt sie fehl.

Lösung:

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

# Pick a different port
jamdesk dev --port 3001

Legen Sie dauerhaft einen Standardport fest, indem Sie "defaultPort": 3001 in Ihre Datei ~/.jamdeskrc eintragen. Überschreiben Sie die Datei nicht, sie kann Ihre Zugangsdaten enthalten.

Wenn der Dev-Server während der Kompilierung beendet wird (erzwungenes Beenden, Systemabsturz), kann der .next-Cache beschädigt werden. Beim nächsten Start erscheinen Meldungen wie „corrupted database“ oder Panik-Fehler.

Lösung:

jamdesk dev --clean

Dies löscht das Verzeichnis .next und startet neu.

Der erste Aufruf von jamdesk dev installiert die Laufzeitabhängigkeiten nach ~/.jamdesk/node_modules. Das geschieht einmalig und kann bei langsameren Verbindungen 1–2 Minuten dauern.

Weitere Starts überspringen die Installation, außer die CLI-Version ändert sich.

npm install läuft beim ersten Start nach 5 Minuten in ein Timeout.

Lösung:

1. Prüfen Sie Ihre Internetverbindung
2. jamdesk clean, um unvollständige Installationen zu entfernen
3. Erneut versuchen
4. Ist npm dauerhaft langsam, prüfen Sie Ihre npm-Registry-Konfiguration: npm config get registry

MDX behandelt < als JSX-Tag-Beginn. Wenn Sie <50% schreiben, entsteht ein Parse-Fehler.

Lösung: Maskieren Sie das Zeichen mit < oder formulieren Sie den Text um. Führen Sie jamdesk validate aus, um Zeilennummern und Vorschläge zu erhalten.

jamdesk broken-links hat interne Links gefunden, die auf nicht existierende Seiten verweisen.

Lösung: Prüfen Sie die Dateipfade. Häufige Fehler: falsche Groß-/Kleinschreibung (Quickstart statt quickstart), die Dateiendung .mdx wurde angegeben oder alte, umbenannte Pfade.

Die CLI schlägt Korrekturen für ähnliche Treffer vor (innerhalb von 3 Zeichen eines Tippfehlers).

Automatisch beheben. Wenn ein defekter Link ein eindeutiges korrektes Ziel hat (ein fehlerhafter Anker oder eine Abweichung des Ankers zwischen Sprachversionen), führen Sie jamdesk fix --dry-run aus, um die Änderungen vorab anzuzeigen, und dann jamdesk fix, um sie anzuwenden. Es werden nur Links umgeschrieben, deren korrigierter Anker eine echte Überschrift auf der Zielseite ist. Mehrdeutige Fälle beheben Sie von Hand. Siehe Defekte Links automatisch beheben.

Die CLI prüft die in docs.json referenzierten OpenAPI-Spezifikationen. Fehler sind unter anderem ungültige $ref-Verweise, fehlende Pflichtfelder oder Syntaxfehler.

Lösung: Führen Sie jamdesk openapi-check path/to/spec.yaml für detaillierte Ausgaben aus. Verwenden Sie den Swagger Editor, um komplexe Spezifikationen zu debuggen.

Nicht global installiert oder Ihre Shell kann das Programm nicht finden.

Lösung:

npm install -g jamdesk

Wenn Sie mit curl installiert haben, stellen Sie sicher, dass ~/.jamdesk/bin in Ihrem PATH liegt.

Die CLI benötigt Schreibzugriff auf ~/.jamdesk (Cache) und ~/.jamdeskrc (Zugangsdaten).

Lösung:

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

jamdesk update führt npm install -g jamdesk@latest aus. Es schlägt fehl, wenn npm Berechtigungsprobleme hat oder die Registry nicht erreichbar ist.

Lösung: Aktualisieren Sie manuell:

npm install -g jamdesk@latest

Schlägt auch das fehl, prüfen Sie npm config get registry und versuchen Sie sudo npm install -g jamdesk@latest.