Most Jamdesk CLI problems have straightforward fixes. This page covers the issues that come up most often, along with the exact commands to resolve them. If something isn’t listed here, the diagnostic commands at the bottom of this page will help you dig deeper.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/jamdesk/jamdesk-cli/llms.txt
Use this file to discover all available pages before exploring further.
Common Issues
"docs.json not found"
"docs.json not found"
This error means the CLI cannot locate a Fix: start a new project from scratchIf you don’t have a
docs.json file in the current directory. Jamdesk expects you to run commands from the root of your docs project — the folder that contains docs.json.Fix: run from the right directorydocs.json yet, create a new project with:Dev server won't start
Dev server won't start
If This inspects your Node.js version, npm, and local configuration, and reports anything that looks wrong.2. Clear the cacheRemoves cached files from Prints detailed logs so you can see exactly where the server is failing.
jamdesk dev exits immediately or fails to load, work through these steps in order:1. Check your environment~/.jamdesk. A stale or corrupted cache is a common cause of startup failures.3. Run with verbose outputTurbopack cache corruption
Turbopack cache corruption
Turbopack cache corruption typically occurs when the dev server is killed mid-build — for example, by a forced terminal close or a system sleep. When the cache is corrupted, the server may crash on startup or fail to compile pages.Fix: clear the cache and restartThis clears the Turbopack cache before starting the server. You don’t need to run any other commands first —
--clean handles everything in one step.Slow first run
Slow first run
The first time you run
jamdesk dev on a new machine or after a fresh install, the CLI installs its dependencies into ~/.jamdesk/node_modules. This is a one-time setup and can take a minute or two depending on your connection speed.Subsequent runs skip this step entirely and start up quickly. If every run feels slow, check whether your ~/.jamdesk directory is being excluded from disk caching by security software or a containerized environment.Port already in use
Port already in use
If port 3000 is occupied by another process, the dev server won’t start on the default port. You have two options:Option 1: specify a different portOption 2: let Jamdesk find an open portThe dev server auto-increments the port number if the default is taken — just run
jamdesk dev without specifying a port and the CLI will report which port it selected.To set a permanent default port, add "defaultPort" to your ~/.jamdeskrc file:MDX syntax errors in JSX
MDX syntax errors in JSX
MDX treats Or rewrite the phrase to avoid the symbol entirely:Find all MDX errors at onceThis reports every MDX syntax error across your project, with file paths and line numbers, so you can fix them all before deploying.
< as the start of a JSX tag. Bare < characters in prose — such as in comparisons like <50% or <= threshold — will cause a parse error.Fix: escape the character or rewrite the phraseUse the HTML entity < in place of <:Diagnostic Commands
When the issue isn’t immediately obvious, these two commands give you the clearest picture of what’s going wrong.jamdesk doctor — inspects your local environment and reports problems with your Node.js version, npm, CLI installation, and project configuration.
jamdesk dev --verbose — runs the dev server with full logging enabled. Every step of startup, compilation, and hot-reload is printed to the terminal.
Getting More Help
If these steps don’t resolve your issue, the following resources are available:- Bug reports and feature requests — github.com/jamdesk/jamdesk-cli/issues
- Direct support — jamdesk.com/docs/help/support/contact