/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Troubleshooting

Troubleshooting

Fixes for the most common build, deploy, domain, and content issues.

3 min read

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 — Cancel on its row under Deployments, or Cancel Build — and re-trigger. A build that has reached deploying can no longer be cancelled. Check status.syntext.dev for platform incidents.

USAGE_LIMIT_EXCEEDED when triggering a build

The API answers 402 with this code when your organization has hit its monthly build quota. Check Billing (account sidebar) 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 Deployments › Previews)
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

Search updates on production deploys — each build rebuilds the index. If results are missing after a big restructure, trigger a new build.

The AI assistant doesn't know about recent changes

The assistant picks up new content after production deploys — preview builds don't update it. Verify the latest production build succeeded.

AI answers are rate-limited too aggressively

The per-visitor limit is a project setting (aiRateLimit) that isn't editable in the dashboard — 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 generate --dry-run to list every detected symbol, and stx check --coverage for the coverage percentage

Drift check fails in CI but the docs look fine

Drift compares signatures (parameter names/types, return type) against the hashes saved by stx check --save-hashes in .syntext/hashes.json. A rename counts as drift even if behavior is unchanged — update the doc comment to match, or regenerate with stx generate, then save the hashes again. Drift is a warning unless CI runs stx check --strict.

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, the key was rotated, or your session was signed out — the API answers 401 session_revoked after a logout everywhere, a password change or reset, or when the session is revoked. Run stx login again, or in CI confirm the key you pass with --token is still active (list keys).

Was this page helpful? Yes No
Next
Product
Resources
Company
© 2026 SyntextBuilt with Syntext