Build Troubleshooting
Fix common build failures by matching error messages to causes and solutions. Covers config errors, missing dependencies, MDX syntax, and icon issues.
The build log shows what broke and where. Find your error message below.
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 usual cause is a stray comma, an unclosed bracket, or 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
Page not found means your navigation points at a file that isn't there. Check the filename against the path in docs.json. Case must match exactly. Leave 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 means the build ran past the time we allow. Large, unoptimized images are the usual cause. Compress them, split very large pages, and remove pages you no longer publish.
Build Warnings
Warnings never fail a build. Your site still publishes. Warnings appear in the build-warnings email, in the build's entry in the Deployments tab, and in the 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. The warning names the page, the line number, and the path it couldn't resolve.
Upload the image, or point the path at a file that exists. Paths are case-sensitive. A path with a leading / resolves from the project root. Any other path resolves relative to the page. A reference to photo.png still works after image optimization converts it to WebP.
Jamdesk skips external URLs, data: URIs, and image syntax inside code blocks.
Debugging Steps
The log names the exact file and line behind the error. Start there.
Run jamdesk dev to reproduce the failure locally.
Run jamdesk validate to check docs.json. Run jamdesk broken-links to find 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