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. If the callback never arrives, the login times out after 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 login URL is always printed to the terminal, even when no browser is available.

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) and 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. Nothing left to upload.

Fix: Check your .gitignore. If it's blocking MDX files or docs.json, the CLI has nothing to work with.

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

Build status is polled every 2 seconds. If your network is flaky, up to 3 consecutive poll failures are tolerated before the CLI gives up.

Fix: Press Ctrl+C. The build keeps running in the background. Check the dashboard for status. A link is printed when you exit.

Upload succeeded, but the build itself failed. You'll see the error from the build service in your terminal.

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.

You'll see a warning when files look like secrets (.env, *.pem, *.key, credentials.json, files starting with secret). This is a warning, not a blocker.

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.

Several things can prevent startup.

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

To set a permanent default, add "defaultPort": 3001 to your ~/.jamdeskrc file. Don't overwrite the file — it may contain your auth credentials.

If the dev server is killed mid-compilation (force quit, system crash), the .next cache can corrupt. You'll see "corrupted database" or panic errors on next startup.

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.

If npm install hangs during the first run, there's a 5-minute timeout.

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).

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.

Write access is needed for ~/.jamdesk (cache) and ~/.jamdeskrc (credentials).

Fix:

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

jamdesk update wraps npm install -g jamdesk@latest. If npm has permission issues or the registry is unreachable, it fails.

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.