> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

Solutions to common issues with HolyDocs builds, deployments, domains, integrations, and more.

## Build Failures

**Invalid docs.json**

**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.

**MDX parse errors**

**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 `&lt;` 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.

**Missing pages in navigation**

**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`.

**OpenAPI spec errors**

**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](https://editor.swagger.io). For remote URLs, verify the URL is publicly accessible and returns valid JSON or YAML.

**Build timeout**

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

## Deployment Issues

**Deployment stuck in 'queued' status**

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.

**Daily build limit exceeded**

**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.

**Token expiry / Bad credentials**

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

## Domain Issues

**Domain not verifying**

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 certificate errors**

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.

**Domain already in use**

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

## Git Integration

**Webhook not firing / builds not triggering**

**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`

**Wrong branch deploying**

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 Issues

**Search returning stale or incorrect results**

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.

**Search not finding specific content**

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

## AI Assistant

**Assistant not responding or giving errors**

- 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

**Assistant giving incorrect answers**

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

## CLI Issues

**holydocs command not found**

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

**Authentication errors in CI**

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_a1b2c3d4e5f67890a1b2c3d4e5f67890
holydocs 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.

## Getting Help

If your issue is not covered here:

**Dashboard Logs**

Check deployment logs in the dashboard for detailed error messages.
  **CLI Verbose Mode**

Re-run the command and copy the exact terminal output. HolyDocs CLI commands currently report actionable errors directly instead of exposing a separate `--verbose` flag.