Troubleshooting

Error: VALIDATION_ERROR: Configuration schema validation failed

Your docs.json has a syntax or schema error. Common causes:

• Missing required fields like name or navigation
• Invalid color format (must be 6-digit hex like #007AFF, not #07F)
• Theme name not matching one of the 8 built-in themes
• JSON syntax errors (trailing commas, missing quotes)

Fix: Run holydocs check locally to see specific validation errors. The CLI provides line-by-line error messages.

Error: MDX_PARSE_ERROR: Failed to parse page.mdx

An MDX file has invalid syntax. Common causes:

• Unclosed JSX tags (e.g., <Callout> without </Callout>)
• Invalid JSX attributes (e.g., cols={3 missing closing brace)
• Raw HTML with unescaped characters (use < instead of < in text)
• Curly braces in content (use {'{'} to escape)

Fix: Check the deployment logs for the specific file and line number. Fix the syntax and push again.

Error: NOT_FOUND: Page 'guides/setup' referenced in navigation but file not found

A page slug in your docs.json navigation does not have a corresponding MDX file.

Fix: Either create the missing MDX file or remove the slug from your navigation configuration. Page slugs map to file paths: "guides/setup" expects guides/setup.mdx.

Error: OPENAPI_ERROR: Failed to parse OpenAPI specification

Your OpenAPI spec is invalid or unreachable. Common causes:

• Spec URL returns a non-JSON/YAML response
• Invalid OpenAPI 3.x syntax
• Unresolvable $ref references
• Network timeout fetching remote spec

Fix: Validate your spec at editor.swagger.io. For remote URLs, verify the URL is publicly accessible and returns valid JSON or YAML.

Error: TIMEOUT: Build exceeded maximum duration

Builds have a 60-second CPU time limit (Cloudflare Worker constraint). Large documentation sites or complex OpenAPI specs can hit this limit.

Fix:

• Reduce the size of inline content in MDX files
• Use remote URLs for OpenAPI specs instead of inline definitions
• Split very large specs into multiple smaller specs
• Contact support if you consistently hit timeouts

Deployments are processed one at a time per project. If a deployment is stuck in queued:

1. Check if another deployment is currently building
2. Wait for the current build to complete or fail
3. If stuck for more than 5 minutes, cancel the deployment from the dashboard and retry

Note: Rapid pushes (multiple commits in quick succession) queue each deployment. Only the latest queued deployment matters — consider canceling intermediate ones.

Error: LIMIT_EXCEEDED: Daily build limit reached

Your plan's daily build limit has been reached. Limits reset at midnight UTC.

Fix: Upgrade your plan for higher limits, or wait for the reset. Use holydocs check locally to validate before pushing to avoid wasting builds on errors.

Error: AUTH_ERROR: Bad credentials or TOKEN_EXPIRED

Your GitHub or GitLab OAuth token has expired or been revoked.

Fix:

1. Go to Settings > Git in the dashboard
2. Click Reconnect GitHub (or GitLab)
3. Re-authorize the HolyDocs app
4. Trigger a manual deployment

After adding a custom domain, verification can take 1-5 minutes (up to 48 hours in rare cases).

Checklist:

• Confirm the CNAME record points to proxy.holydocs.com
• Check for conflicting A records on the same hostname
• Verify DNS propagation with dig docs.yourcompany.com CNAME
• If using Cloudflare DNS, the orange proxy cloud is supported but not required
• Try removing and re-adding the domain in the dashboard

SSL certificates are auto-provisioned after DNS verification. If SSL is not working:

1. Verify the domain shows as "verified" in the dashboard
2. Wait 1-2 minutes after verification for certificate provisioning
3. Clear your browser cache and try again
4. If still broken after 10 minutes, remove and re-add the domain

Note: Apex domains require CNAME flattening support from your DNS provider.

Each custom domain can only be assigned to one HolyDocs project. If you see "already in use":

• Check all projects in your organization for the domain
• The domain may be assigned to a deleted project — contact support
• If transferring from another organization, the other org must release it first

Checklist:

• Verify the webhook exists: GitHub Repo > Settings > Webhooks (or GitLab equivalent)
• Check the webhook URL is https://api.holydocs.com/api/v1/webhooks/github (or /gitlab)
• Look at recent webhook deliveries in GitHub for error responses
• Ensure push events are enabled for the webhook
• For monorepos, verify changes are within the configured repoPath

Verify the branch configuration in Settings > Git. The default branch should match your repository's primary branch (usually main or master). Pushes to other branches create preview deployments (Pro+ only).

Search indices are rebuilt on every production deployment. If results seem stale:

1. Trigger a manual reindex: AI Features > Reindex Content in the dashboard
2. Wait 30-60 seconds for indexing to complete
3. Test search again

Content indexing uses differential checksums — only changed pages are re-embedded.

Keyword search weights titles highest, then headings, then body content. If a page is not appearing:

• Verify the page is listed in the navigation (unlisted pages are not indexed)
• Check that the page has a title and description in frontmatter
• For semantic search, try rephrasing the query — it understands intent, not just keywords

• Verify the assistant is enabled: check assistant.enabled: true in docs.json
• Check your plan's AI message quota in the dashboard under AI Features > Usage
• If using a custom model override, verify the model name is valid
• Try clearing browser cache and reloading the page

The assistant answers based on your documentation content. If answers are wrong:

1. Check if the relevant content exists in your docs
2. Trigger a reindex to ensure the latest content is embedded
3. Improve the content — better documentation produces better AI answers
4. Add suggested questions to guide users toward common topics

The CLI is not installed globally or not in your PATH.

Fix:

bash
npm install -g @holydocs/cli

Or use npx without installing:

bash
npx @holydocs/cli <command>

In CI environments there's no browser, so the device login flow won't work. Use the HOLYDOCS_API_KEY environment variable instead:

bash
export HOLYDOCS_API_KEY=hd_a1b2c3d4e5f67890a1b2c3d4e5f67890holydocs deploy --project proj_abc123

The CLI reads HOLYDOCS_API_KEY automatically — no holydocs login step required. Generate API keys from Settings → API Keys in the dashboard.