Build Error Reference

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—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 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—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 for common issues
3. Contact support with your project ID and error details

Related Articles