---
title: Troubleshooting
description: "Fixes for the most common build, deploy, domain, and content issues."
---

# Troubleshooting

Solutions to the most common issues, grouped by area. Still stuck? Ask in [Discord](https://discord.gg/syntext) or email support@syntext.dev.

## Builds

### Build fails with an MDX compile error

The build log names the file and line. The most common causes:

- **Unclosed JSX tags** — every `<Note>` needs `</Note>`
- **`<` or `{` in prose** — MDX treats them as JSX/expressions. Escape as `\<`, `\{`, or wrap in backticks
- **Invalid frontmatter YAML** — usually unquoted strings containing `:`

Run [`stx build`](/cli/build) locally to reproduce with the exact same compiler before pushing.

### Build stays queued for a long time

Builds are processed in order per project. If a build appears stuck, [cancel it](/api-reference/builds/cancel) and re-trigger. Check [status.syntext.dev](https://status.syntext.dev) for platform incidents.

### `USAGE_LIMIT_EXCEEDED` when triggering a build

Your organization hit its monthly build quota. Check **Organization → Billing** in the dashboard. PR preview builds count toward the quota — consider limiting preview triggers to docs-related paths.

### Push to GitHub didn't trigger a build

1. Confirm the push was to the project's configured branch (other branches build **previews**, visible under Builds with the preview flag)
2. GitHub repo → **Settings → Webhooks → Recent Deliveries** — look for red ✗ deliveries
3. A `401 Invalid signature` response means the webhook secret doesn't match — see [Webhooks](/api-reference/webhooks/overview)

## Deploys & Domains

### Custom domain shows an SSL error

Certificates are issued after DNS verification. Check:

1. The CNAME record points exactly where the dashboard says (no proxying through another CDN during verification)
2. Verification status via [Verify Domain](/api-reference/domains/verify)
3. DNS propagation can take up to an hour — retry verification after propagation

### Old content still showing after a deploy

Deploys are atomic, but your browser may cache aggressively. Hard-refresh first. If stale content persists across browsers, confirm the build actually reached `deployed` status — a `failed` build leaves the previous deploy live (by design).

## Search & AI

### Search returns no results for content that exists

The index is rebuilt on production deploys. If results are missing after a big restructure, trigger a manual [reindex](/api-reference/search/reindex).

### The AI assistant doesn't know about recent changes

Embeddings update after **production** deploys — preview builds are not indexed. Verify the latest production build succeeded.

### AI answers are rate-limited too aggressively

Raise the per-visitor limit under **Settings → AI Assistant** — see [Rate Limits](/api-reference/rate-limits).

## Annotations

### Symbols missing from the generated API reference

- Check the file extension is [supported](/concepts/annotations)
- Symbols marked `@internal`, `@private`, or `@hidden` are excluded by design
- The comment must directly precede the declaration (framework decorators/attributes in between are OK)
- Run `stx check` locally — it lists every detected symbol and its coverage status

### Drift check fails in CI but the docs look fine

Drift compares **signatures** (parameter names/types, return type) against what was last documented. A rename counts as drift even if behavior is unchanged — update the doc comment to match, or regenerate with `stx generate`.

## CLI

### `stx: command not found`

```bash
brew install syntext-dev/tap/stx     # macOS
curl -fsSL https://get.syntext.dev | sh   # Linux/CI
```

### `stx deploy` says unauthorized

Your credential expired or the key was rotated. Run `stx login` again, or in CI confirm the `SYNTEXT_API_KEY` secret matches an active key ([list keys](/api-reference/api-keys/list)).