Troubleshooting

Each section has a quick fix and a link to the full guide in the Help Center.

Build Failures

Your dashboard shows a build as "Failed". Common causes:

• An MDX page with a broken import or component.
• Invalid docs.json (unclosed brackets, trailing commas after the last array item).
• A page listed in docs.json navigation that doesn't exist as an .mdx file.

Run jamdesk dev before you push. It catches the first two locally.

For specific error codes, see Build Failures and the Error Reference.

Custom Domain Not Verifying

If your domain stays "Pending" after you add the DNS records, check these in order:

1. Confirm you added the _jamdesk.<hostname> TXT record. Routing doesn't activate without it. A missing TXT record is the most common cause of a Pending domain. The hostname is the full domain you're verifying (for docs.example.com, the TXT record name is _jamdesk.docs.example.com).
2. Confirm you added a CNAME record (not an A record) for subdomains.
3. If you're on Cloudflare, set the proxy to DNS only (gray cloud) for both records.
4. Check propagation at whatsmydns.net.

# Verify the TXT verification record
dig TXT _jamdesk.docs.yourdomain.com

# Verify your CNAME is resolving
dig CNAME docs.yourdomain.com

The dashboard can report "Pending" for up to 30 minutes after dig shows your records resolving. The verifier sits behind upstream resolvers that cache negative DNS responses. Wait half an hour before you look for a deeper problem.

DNS Troubleshooting covers provider-specific gotchas.

Valid OpenAPI Spec Fails to Validate

jamdesk dev rejects a valid spec with errors like #/servers/0/variables/host must NOT have unevaluated properties. This usually hits server variables that carry a description, or a license with only a name. The CLI's copy of the OpenAPI 3.1 meta-schema is the problem. npm 12 blocks package install scripts by default. That skips the step that corrects two known defects in the schema.

Upgrade the CLI. Version 1.1.167 and later repair the schema at validation time:

npm install -g jamdesk@latest

On an older pinned version, run npm install -g --allow-scripts=jamdesk jamdesk to let the install step run.

GitHub Repository Not Appearing

A repo missing from the list usually means the Jamdesk GitHub App isn't installed on the repo's organization. Repository access may also be set to "Selected repositories" without yours. Re-authorize at github.com/settings/installations and grant access to "All repositories" or the specific repo.

See GitHub Issues for webhook and permission problems.

Analytics Data Missing

Analytics take up to 24 hours to appear after a site's first deploy. Ad blockers and Do Not Track stop some visits from being counted. Your numbers will always trail your server logs. If your dashboard still shows zero visitors, confirm your site is deployed and publicly accessible.

Analytics Issues goes deeper on delayed or missing data.

Login Problems

If you can't sign in or get bounced back to the login screen, clear cache and cookies for dashboard.jamdesk.com. Then try an incognito window. GitHub sign-in requires your GitHub email to match the email on your Jamdesk account.

See Login Issues for account recovery steps.

Still Stuck?