Troubleshooting
Fixes for the most common build, deploy, domain, and content issues.
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:
<Note> needs </Note>< or { in prose — MDX treats them as JSX/expressions. Escape as \<, \{, or wrap in backticks: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
401 Invalid signature response means the webhook secret doesn't match — see WebhooksDeploys & Domains
Custom domain shows an SSL error
Certificates are issued after DNS verification. Check:
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
@internal, @private, or @hidden are excluded by designstx generate --dry-run to list every detected symbol, and stx check --coverage for the coverage percentageDrift 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
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).