Guides
View as Markdown Open in ChatGPT Open in Claude

Troubleshooting

Solutions to the most common issues, grouped by area. Still stuck? Ask in Discord 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 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 and re-trigger. Check 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

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

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.

Annotations

Symbols missing from the generated API reference

  • Check the file extension is supported
  • 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

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

Was this page helpful?