Build Troubleshooting
Fix common build failures by matching error messages to causes and solutions.
When a build fails, check the error message in the build log and find the matching section below.
Viewing Error Details
- Go to your project's Deployments tab
- Click the failed build
- Review the error message and build log
The log shows exactly where the build failed and why.
Common Errors
Configuration Errors
"Invalid docs.json" — Your configuration file has syntax errors.
Look for missing commas, brackets, or quotes.
Run jamdesk validate to see detailed errors.
Correct the errors and push to trigger a new build.
Missing Pages
"Page not found" — A page in your navigation doesn't exist.
- Check the filename matches the path in
docs.json - Paths are case-sensitive
- Don't include the
.mdxextension
MDX Syntax Errors
"MDX compilation failed" — Invalid MDX or JSX syntax.
Common causes:
- Unclosed tags (
<Card>without</Card>) - Unescaped special characters (
{instead of\{) - Invalid prop syntax
Build Timeout
"Build exceeded time limit" — Build took too long.
Try:
- Optimizing large images
- Splitting very large pages
- Reducing total page count
Debugging Steps
The log shows the exact line and file causing the error. Start there.
Run jamdesk dev locally to reproduce and debug the issue.
Run jamdesk validate to check your docs.json and jamdesk broken-links for broken internal links.
Review your last commit. Did you add a new page? Change configuration?
Still Stuck?
If you can't resolve the issue:
- Copy the full build log
- Note your project ID (in URL)
- Contact support