CLI-Probleme

Deine gespeicherten Anmeldedaten fehlen oder das Refresh-Token ist nicht mehr gültig.

Lösung: Führe jamdesk login aus, um eine neue Sitzung zu starten. Dadurch wird der bisherige Inhalt von ~/.jamdeskrc ersetzt.

Wenn der Fehler direkt nach der Anmeldung erneut auftritt, überprüfe, ob ~/.jamdeskrc geschrieben wurde:

cat ~/.jamdeskrc

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

Die CLI startet einen lokalen Server auf Port 9876, um den Authentifizierungs-Callback deines Browsers zu empfangen. Wenn der Callback nicht eintrifft, läuft die Anmeldung nach 2 Minuten ab.

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, aber die URL muss übereinstimmen)

Lösung: Kopiere die im Terminal ausgegebene URL und öffne sie manuell. Überprüfe, ob die Portnummer in der URL mit dem Port übereinstimmt, auf dem die CLI lauscht.

Dies ist in Headless-Umgebungen normal, etwa bei SSH-Sitzungen, Docker-Containern und CI-Runnern. Die Anmelde-URL wird immer im Terminal ausgegeben, auch wenn kein Browser verfügbar ist.

Kopiere sie und öffne sie in einem beliebigen Browser, der deine Maschine am Callback-Port erreichen kann.

Wenn du dein Jamdesk-Passwort änderst, werden alle vorhandenen Refresh-Tokens ungültig. Die CLI erkennt dies (TOKEN_EXPIRED oder INVALID_REFRESH_TOKEN) und löscht die gespeicherten Authentifizierungsdaten automatisch.

Führe jamdesk login erneut aus.

Pro Projekt kann jeweils nur ein Build ausgeführt werden. Die CLI gibt diesen Fehler (Code BUILD_IN_PROGRESS) zurück, wenn ein Build in der Warteschlange steht oder ausgeführt wird.

Lösung: Warte, bis der aktuelle Build abgeschlossen ist. Überprüfe den Status unter Deployments im Dashboard. Wenn ein Build festzustecken scheint, bitte den Projekteigentümer, das Dashboard zu überprüfen.

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

Lösung:

1. Stelle sicher, dass du dich im richtigen Verzeichnis befindest: ls docs.json
2. Führe jamdesk validate aus, um genaue Fehlerdetails zu erhalten
3. Überprüfe fehlende Kommas, nicht geschlossene Klammern oder nachgestellte Kommas (die CLI verwendet für docs.json JSON, nicht JSON5)

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

Lösung: Überprüfe, welche Dateien einbezogen werden. Häufige Ursachen sind Videodateien, große PDFs, unkomprimierte Bilder und Datendumps. Füge sie zu .gitignore hinzu.

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

Jede Datei entspricht einem Ausschlussmuster. Es ist nichts zum Hochladen übrig.

Lösung: Überprüfe deine .gitignore. Wenn sie MDX-Dateien oder docs.json blockiert, kann die CLI nicht arbeiten.

Entweder entspricht die projectId in docs.json keinem Projekt in deinem Konto, oder du bist kein Mitglied dieses Projekts.

Lösung:

• Entferne das Feld projectId aus docs.json und führe jamdesk deploy erneut aus, um ein neues Projekt auszuwählen
• Überprüfe, ob du mit dem richtigen Konto angemeldet bist: jamdesk whoami
• Überprüfe die Projektmitgliedschaft im Dashboard

Der Build-Status wird alle 2 Sekunden abgefragt. Wenn deine Netzwerkverbindung instabil ist, werden bis zu 3 aufeinanderfolgende fehlgeschlagene Abfragen toleriert, bevor die CLI abbricht.

Lösung: Drücke Strg+C. Der Build wird im Hintergrund weiter ausgeführt. Überprüfe den Status im Dashboard. Beim Beenden wird ein Link ausgegeben.

Der Upload war erfolgreich, aber der Build selbst ist fehlgeschlagen. Der Fehler des Build-Dienstes wird in deinem Terminal angezeigt.

Lösung: Überprüfe das Build-Log im Dashboard unter Deployments. Häufige Ursachen sind MDX-Syntaxfehler, in der Navigation referenzierte fehlende Seiten und ungültige OpenAPI-Spezifikationen. Führe lokal jamdesk validate aus, um diese Probleme vor der Bereitstellung zu erkennen.

Du siehst eine Warnung, wenn Dateien wie Geheimnisse aussehen (.env, *.pem, *.key, credentials.json, Dateien, die mit secret beginnen). Dies ist eine Warnung und keine Blockierung.

Lösung: Füge die Dateien zu .gitignore hinzu, um sie von Uploads auszuschließen. Wenn sie absichtlich enthalten sind, etwa Beispieldateien mit Schlüsseln in deiner Dokumentation, ignoriere die Warnung.

Mehrere Ursachen können den Start verhindern.

Versuche es in dieser Reihenfolge:

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

Die CLI versucht 10 aufeinanderfolgende Ports ab deinem angeforderten Port (standardmäßig 3000). Wenn alle 10 belegt sind, schlägt sie fehl.

Lösung:

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

# Pick a different port
jamdesk dev --port 3001

Um einen dauerhaften Standardwert festzulegen, füge "defaultPort": 3001 zu deiner Datei ~/.jamdeskrc hinzu. Überschreibe die Datei nicht, da sie deine Authentifizierungsdaten enthalten kann.

Wenn der Dev-Server während der Kompilierung beendet wird, etwa durch erzwungenes Beenden oder einen Systemabsturz, kann der .next-Cache beschädigt werden. Beim nächsten Start werden dann möglicherweise Fehler wie „corrupted database“ oder Panic-Fehler angezeigt.

Lösung:

jamdesk dev --clean

Dadurch wird das Verzeichnis .next gelöscht und ein sauberer Start durchgeführt.

Beim ersten jamdesk dev werden Laufzeitabhängigkeiten in ~/.jamdesk/node_modules installiert. Dies geschieht einmalig und kann bei langsameren Verbindungen 1–2 Minuten dauern.

Bei nachfolgenden Läufen wird die Installation übersprungen, sofern sich die CLI-Version nicht ändert.

Wenn npm install beim ersten Lauf hängt, gilt eine Zeitüberschreitung von 5 Minuten.

Lösung:

1. Überprüfe deine Internetverbindung
2. Führe jamdesk clean aus, um unvollständige Installationen zu löschen
3. Versuche es erneut
4. Wenn npm dauerhaft langsam ist, überprüfe deine npm-Registry-Konfiguration: npm config get registry

MDX behandelt < als Beginn eines JSX-Tags. Das Schreiben von <50% führt zu einem Parse-Fehler.

Lösung: Maskiere das Zeichen mit < oder formuliere den Ausdruck um. Führe jamdesk validate aus, um Zeilennummern und Vorschläge zu erhalten.

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

Lösung: Überprüfe die Dateipfade. Häufige Fehler sind falsche Groß-/Kleinschreibung (Quickstart statt quickstart), die Verwendung der .mdx-Erweiterung oder alte, umbenannte Pfade.

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

Automatisch korrigieren. Wenn ein defekter Link ein eindeutig korrektes Ziel hat, etwa ein fehlerhafter Anchor oder ein Anchor-Drift zwischen Locales, führe jamdesk fix --dry-run aus, um die Änderungen in der Vorschau anzuzeigen, und anschließend jamdesk fix, um sie anzuwenden. Es werden nur Links umgeschrieben, deren korrigierter Anchor eine echte Überschrift auf der Zielseite ist. Mehrdeutige Fälle musst du manuell korrigieren. Siehe Defekte Links automatisch korrigieren.

Die CLI validiert die in docs.json referenzierten OpenAPI-Spezifikationen. Zu den Fehlern gehören ungültige $ref-Referenzen, fehlende erforderliche Felder oder Syntaxfehler.

Lösung: Führe jamdesk openapi-check path/to/spec.yaml aus, um eine detaillierte Ausgabe zu erhalten. Verwende den Swagger Editor, um komplexe Spezifikationen zu debuggen.

Nicht global installiert, oder deine Shell kann die Binärdatei nicht finden.

Lösung:

npm install -g jamdesk

Wenn du die Installation mit curl durchgeführt hast, stelle sicher, dass sich ~/.jamdesk/bin in deinem PATH befindet.

Schreibzugriff ist für ~/.jamdesk (Cache) und ~/.jamdeskrc (Anmeldedaten) erforderlich.

Lösung:

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

jamdesk update ist ein Wrapper für npm install -g jamdesk@latest. Wenn npm Berechtigungsprobleme hat oder die Registry nicht erreichbar ist, schlägt der Befehl fehl.

Lösung: Aktualisiere manuell:

npm install -g jamdesk@latest

Wenn auch das fehlschlägt, überprüfe npm config get registry und versuche sudo npm install -g jamdesk@latest.