---
title: Build Error Reference
description: Every build error code with its root cause and fix -- configuration, MDX syntax, OpenAPI, timeouts, and asset issues.
---

Find your error code with Ctrl/Cmd+F or browse by category: configuration, MDX, OpenAPI, timeouts, and assets.

## Configuration Errors

### INVALID_DOCS_JSON

**Message:** "Invalid docs.json configuration"

**Cause:** Your `docs.json` file has syntax errors or invalid values.

**Fix:**
1. Run `jamdesk validate` locally to see detailed errors
2. Check for missing commas, brackets, or quotes
3. Verify all values match the expected schema

### MISSING_PAGE

**Message:** "Page 'path/to/page' referenced in navigation but file not found"

**Cause:** A page listed in `docs.json` navigation doesn't exist.

**Fix:**
1. Check the file exists at the specified path
2. Verify the path in `docs.json` matches the actual filename (without `.mdx`)
3. Paths are case-sensitive, so check capitalization

### INVALID_FRONTMATTER

**Message:** "Invalid frontmatter in 'path/to/page'"

**Cause:** The YAML frontmatter at the top of an MDX file is malformed.

**Fix:**
1. Ensure frontmatter starts and ends with `---`
2. Check for invalid YAML syntax (missing colons, bad indentation)
3. Quote strings that contain special characters

## MDX Errors

### MDX_SYNTAX_ERROR

**Message:** "MDX compilation failed"

**Cause:** Invalid MDX or JSX syntax in your content.

**Fix:**
1. Ensure all JSX tags are properly closed (`<Card>...</Card>`)
2. Check that props use correct syntax (`title="value"` not `title=value`)
3. Escape curly braces in regular text: `\{` instead of `{`

### COMPONENT_NOT_FOUND

**Message:** "Unknown component 'ComponentName'"

**Cause:** Using a component that doesn't exist in Jamdesk.

**Fix:**
1. Check [Components reference](/components/overview) for correct names
2. Components are case-sensitive: use `<Card>` not `<card>`
3. Verify you're not importing custom components (not supported)

### INVALID_PROPS

**Message:** "Invalid props for component 'ComponentName'"

**Cause:** A component received props it doesn't accept.

**Fix:**
1. Check the component documentation for valid props
2. Remove any unsupported props
3. Ensure prop values are the correct type

## OpenAPI Errors

### OPENAPI_PARSE_ERROR

**Message:** "Failed to parse OpenAPI specification"

**Cause:** Your OpenAPI spec file has invalid syntax or structure.

**Fix:**
1. Run `jamdesk openapi-check` to validate locally
2. Use an OpenAPI validator like Swagger Editor
3. Check for valid JSON or YAML syntax

### OPENAPI_REFERENCE_ERROR

**Message:** "Unresolved reference in OpenAPI spec"

**Cause:** A `$ref` in your OpenAPI spec points to a non-existent definition.

**Fix:**
1. Verify all `$ref` paths are correct
2. Check that referenced schemas exist in `components/schemas`
3. Ensure external references are accessible

## Build Timeout

### BUILD_TIMEOUT

**Message:** "Build exceeded maximum time limit"

**Cause:** The build took longer than the allowed time (usually 5 minutes).

**Fix:**
1. Optimize large images (compress or resize)
2. Split very large pages into smaller ones
3. Reduce the number of pages if extremely large
4. Contact support if the issue persists

## Asset Errors

### ASSET_NOT_FOUND

**Message:** "Asset 'path/to/asset' not found"

**Cause:** An image or file referenced in your docs doesn't exist.

**Fix:**
1. Verify the file exists at the specified path
2. Check the path is relative to your docs directory
3. Paths are case-sensitive, so check the filename exactly

### ASSET_TOO_LARGE

**Message:** "Asset exceeds maximum file size"

**Cause:** An image or file is larger than the 10MB limit.

**Fix:**
1. Compress images using tools like TinyPNG or ImageOptim
2. Use appropriate formats (WebP for photos, SVG for icons)
3. Consider hosting very large files externally

## Getting Help

If you can't resolve an error:

1. Check the full build log in your dashboard for more context
2. Search the [FAQ](/help/faq) for common issues
3. [Contact support](/help/support/contact) with your project ID and error details

## Related Articles

<Columns cols={2}>
  <Card title="Build Failures" icon="triangle-exclamation" href="/help/troubleshooting/build-failures">
    Common build failures and solutions
  </Card>
  <Card title="Contact Support" icon="headset" href="/help/support/contact">
    Get help from our team
  </Card>
</Columns>