Troubleshooting

Start here when something isn't working. Each section gives a quick fix and links to the full guide in the Help Center.

Build Failures

Symptom: Build status shows "Failed" in the dashboard.

Quick checks:

1. Run jamdesk dev locally to catch MDX syntax errors
2. Verify docs.json is valid JSON (missing commas, trailing commas)
3. Check that all pages listed in navigation exist as .mdx files

See Build Failures and Error Reference for specific error codes.

Custom Domain Not Verifying

Symptom: Domain stuck on "Pending" after adding DNS records.

Quick checks:

1. Confirm you added a CNAME record (not A record) for subdomains
2. If using Cloudflare, set proxy to DNS only (gray cloud)
3. Check propagation at whatsmydns.net

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

See DNS Troubleshooting for provider-specific guidance.

GitHub Repository Not Appearing

Symptom: Your repo doesn't show up when creating a project.

Quick checks:

1. Verify the Jamdesk GitHub App is installed on the repo's organization
2. Check that repository access is set to "All repositories" or the specific repo is selected
3. Re-authorize at github.com/settings/installations

See GitHub Issues for webhook and permission problems.

Analytics Data Missing

Symptom: Dashboard shows zero visitors or stale data.

Quick checks:

1. Analytics take up to 24 hours to appear after first deploy
2. Ad blockers and Do Not Track prevent some visits from being counted
3. Verify your site is deployed and publicly accessible

See Analytics Issues for delayed or missing data.

Login Problems

Symptom: Can't sign in or getting redirected to login repeatedly.

Quick checks:

1. Clear browser cache and cookies for dashboard.jamdesk.com
2. Try an incognito/private window
3. If using GitHub SSO, verify your GitHub email matches your Jamdesk account

See Login Issues for account recovery steps.

Still Stuck?