---
title: Build Troubleshooting
description: "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, check the error message in the build log and find the matching section below.

## Viewing Error Details

1. Go to your project's **Deployments** tab
2. Click the failed build
3. 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.

<Steps>
  <Step title="Check JSON syntax">
    Look for missing commas, brackets, or quotes.
  </Step>
  <Step title="Validate locally">
    Run `jamdesk validate` to see detailed errors.
  </Step>
  <Step title="Fix and push">
    Correct the errors and push to trigger a new build.
  </Step>
</Steps>

### 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 `.mdx` extension

### 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

<Accordion title="Step 1: Check the build log">
  The log shows the exact line and file causing the error. Start there.
</Accordion>

<Accordion title="Step 2: Test locally">
  Run `jamdesk dev` locally to reproduce and debug the issue.
</Accordion>

<Accordion title="Step 3: Validate configuration">
  Run `jamdesk validate` to check your `docs.json` and `jamdesk broken-links` for broken internal links.
</Accordion>

<Accordion title="Step 4: Check recent changes">
  Review your last commit. Did you add a new page? Change configuration?
</Accordion>

## Still Stuck?

If you can't resolve the issue:

1. Copy the full build log
2. Note your project ID (in URL)
3. [Contact support](/help/support/contact)

## Related Articles

<Columns cols={2}>
  <Card title="Error Reference" icon="book" href="/help/troubleshooting/error-reference">
    All error codes explained
  </Card>
  <Card title="Monitoring Builds" icon="chart-line" href="/builds/monitoring">
    Track build progress
  </Card>
</Columns>