Build Troubleshooting
Fix common build failures by matching error messages to causes and solutions. Covers config errors, missing dependencies, MDX syntax, and icon issues.
When a build fails, the build log tells you what broke and where. Find your error message below and jump to the fix.
Viewing Error Details
- Open your project's Deployments tab
- Click the failed build
- Read the error message and scroll through the build log
The log points to the exact file and line that stopped the build.
Common Errors
Configuration Errors
Invalid docs.json means your configuration file won't parse. The cause is almost always small: a stray comma, an unclosed bracket, a missing quote.
Look for missing commas, brackets, or quotes.
Run jamdesk validate to see the exact errors.
Correct them and push to trigger a new build.
Missing Pages
A Page not found error fires when your navigation points at a file that isn't there. Check that the filename matches the path in docs.json, that the case lines up exactly, and that you left off the .mdx extension.
MDX Syntax Errors
MDX compilation failed points to malformed MDX or JSX on a page. Usually it's an unclosed tag (a <Card> with no matching </Card>), an unescaped character such as a literal { where you meant \{, or invalid prop syntax.
Build Timeout
Build exceeded time limit is exactly what it says: the build ran past the time we allow. Large, unoptimized images are the usual culprit. Compress them, split any pages that have grown huge, and drop pages you no longer publish.
Build Warnings
Warnings never fail a build; your site still publishes either way. They flag issues worth fixing and surface in three places: the build-warnings email, the build's entry in the Deployments tab, and your terminal when you run jamdesk validate or jamdesk dev.
Missing Images
Image not found warns that a page references an image your project doesn't contain.
Jamdesk checks every image reference (Markdown  plus the src on <img loading="lazy"> and <Image> tags) against the files in your repository. When the target is missing, the warning hands you the page, the line number, and the path it couldn't resolve, so a broken image never ships as a silent 404.
To fix it, upload the image or repoint the path at a file that exists. Paths are case-sensitive and resolve either from your project root (a leading /) or relative to the page. And a reference to photo.png still works after image optimization converts it to WebP.
References to external URLs, data: URIs, and image syntax shown inside code blocks are skipped, so the examples in your own docs never trip a false warning.
Debugging Steps
The log names the exact file and line behind the error. Start there.
Run jamdesk dev to reproduce the failure on your own machine.
Run jamdesk validate to check your docs.json, then jamdesk broken-links to catch broken internal links.
Look at your last commit. Did you add a page or change configuration?
Still Stuck?
If none of the above resolves it:
- Copy the full build log
- Note your project ID (it's in the URL)
- Contact support