CLI Issues

Your stored credentials are missing or the refresh token is no longer valid.

Fix: Run jamdesk login to start a fresh session. This replaces whatever was in ~/.jamdeskrc.

If the error keeps coming back immediately after logging in, check that ~/.jamdeskrc was written:

cat ~/.jamdeskrc

The file should contain an auth object with refreshToken, email, and uid. If it's empty or missing, your home directory may have permission issues.

The CLI starts a local server on port 9876 to receive the auth callback from your browser. The login times out if the callback doesn't arrive within 2 minutes.

Common causes:

• A firewall is blocking the local server
• The browser tab was closed before completing authentication
• Port 9876 is taken (the CLI auto-picks another port, but the URL must match)

Fix: Copy the URL printed in the terminal and open it manually. Check that the port number in the URL matches what the CLI is listening on.

Normal in headless environments (SSH sessions, Docker containers, CI runners). The CLI always prints the login URL to the terminal.

Copy it and open in any browser that can reach your machine on the callback port.

Changing your Jamdesk password invalidates all existing refresh tokens. The CLI detects this (TOKEN_EXPIRED or INVALID_REFRESH_TOKEN). It clears stored auth automatically.

Run jamdesk login again.

Only one build runs at a time per project. The CLI returns this error (code BUILD_IN_PROGRESS) when a build is queued or running.

Fix: Wait for the current build to finish. Check Deployments in the dashboard for status. If a build appears stuck, ask the project owner to check the dashboard.

No docs.json in the current directory, or it has JSON syntax errors.

Fix:

1. Make sure you're in the right directory: ls docs.json
2. Run jamdesk validate for specific error details
3. Check for missing commas, unclosed brackets, or trailing commas (the CLI uses JSON, not JSON5 for docs.json)

Your compressed tarball exceeds the 100 MB limit. Everything not excluded by .gitignore or the built-in exclusion list gets packaged.

Fix: Check what's being included. Common culprits: video files, large PDFs, uncompressed images, data dumps. Add them to .gitignore.

Always excluded regardless of .gitignore: .git, node_modules, .next, .env*, *.pem, *.key, credentials.json, .DS_Store.

Every file matched an exclusion pattern.

Fix: Check that your .gitignore doesn't exclude MDX files or docs.json.

Either the projectId in docs.json doesn't match any project in your account, or you're not a member of that project.

Fix:

• Remove the projectId field from docs.json and re-run jamdesk deploy to pick a new project
• Verify you're logged in as the right account: jamdesk whoami
• Check project membership in the dashboard

The CLI polls build status every 2 seconds. It gives up after 3 consecutive poll failures.

Fix: Press Ctrl+C. The build keeps running in the background. Check the dashboard for status. The CLI prints a link when you exit.

The upload succeeded. The build failed. The terminal shows the error from the build service.

Fix: Check the build log in the dashboard under Deployments. Common causes: MDX syntax errors, missing pages referenced in navigation, invalid OpenAPI specs. Run jamdesk validate locally to catch these before deploying.

The CLI warns about files that look like secrets (.env, *.pem, *.key, credentials.json, files starting with secret). The warning doesn't block the deploy.

Fix: Add the files to .gitignore to exclude them from uploads. If they're intentional (e.g., example key files in your docs), ignore the warning.

Try in order:

1. jamdesk doctor to check Node.js version (v20+ required) and environment
2. jamdesk clean to clear cached dependencies
3. jamdesk dev --verbose for detailed error output
4. jamdesk dev --clean to clear the build cache before starting

The CLI tries 10 consecutive ports starting from your requested port (default 3000). If all 10 are taken, it fails.

Fix:

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

# Pick a different port
jamdesk dev --port 3001

Set a permanent default by adding "defaultPort": 3001 to your ~/.jamdeskrc file. Don't overwrite the file. It may contain your auth credentials.

Killing the dev server mid-compilation (force quit, system crash) can corrupt the .next cache. The next startup shows "corrupted database" or panic errors.

Fix:

jamdesk dev --clean

This wipes the .next directory and starts fresh.

The first jamdesk dev installs runtime dependencies to ~/.jamdesk/node_modules. This happens once and can take 1-2 minutes on slower connections.

Subsequent runs skip the install unless the CLI version changes.

npm install on the first run times out after 5 minutes.

Fix:

1. Check your internet connection
2. jamdesk clean to clear partial installs
3. Try again
4. If npm is consistently slow, check your npm registry configuration: npm config get registry

MDX treats < as a JSX tag opener. Writing <50% causes a parse error.

Fix: Escape with < or rewrite. Run jamdesk validate for line numbers and suggestions.

jamdesk broken-links found internal links pointing to pages that don't exist.

Fix: Check the file paths. Common mistakes: wrong case (Quickstart vs quickstart), including the .mdx extension, or old paths that were renamed.

The CLI suggests corrections for close matches (within 3 characters of a typo).

Fix them automatically. If a broken link has an unambiguous correct target (a typo'd anchor or cross-locale anchor drift), run jamdesk fix --dry-run to preview the changes, then jamdesk fix to apply them. It only rewrites links whose corrected anchor is a real heading on the target page. Fix ambiguous cases by hand. See Auto-fix broken links.

The CLI validates OpenAPI specs referenced in docs.json. Failures include invalid $ref references, missing required fields, or syntax errors.

Fix: Run jamdesk openapi-check path/to/spec.yaml for detailed output. Use the Swagger Editor to debug complex specs.

Not installed globally, or your shell can't find the binary.

Fix:

npm install -g jamdesk

If you installed with curl, make sure ~/.jamdesk/bin is in your PATH.

The CLI needs write access to ~/.jamdesk (cache) and ~/.jamdeskrc (credentials).

Fix:

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

jamdesk update wraps npm install -g jamdesk@latest. It fails when npm has permission issues or the registry is unreachable.

Fix: Update manually:

npm install -g jamdesk@latest

If that also fails, check npm config get registry and try sudo npm install -g jamdesk@latest.