Troubleshooting
Quick fixes for common Jamdesk issues including build failures, DNS verification, GitHub connections, and missing analytics data.
Start here when something isn't working. Each section has a quick fix and a link to the deeper guide in the Help Center.
For account, billing, or product questions that aren't covered here, head straight to the Help Center.
Build Failures
Your dashboard shows a build as "Failed". Most failures come from one of three things: an MDX page with a broken import or component, an invalid edit to docs.json (unclosed brackets, trailing commas after the last array item), or a page listed in docs.json navigation that doesn't exist as an .mdx file. The first two surface locally with jamdesk dev before they ever reach a deployed build. Running it once before pushing tends to save a round trip.
The build log in your dashboard shows the exact file and line where the error occurred. Start there — it's almost always pointing at the real problem, not just the symptom.
For specific error codes, see Build Failures and the Error Reference.
Custom Domain Not Verifying
Domain stuck on "Pending" after you added the DNS records? Run through these in order:
- Confirm you added the
_jamdesk.<hostname>TXT record. Routing doesn't activate without it, and missing TXT is the single most common cause of a Pending domain. The hostname is the full domain you're verifying (fordocs.example.com, the TXT record name is_jamdesk.docs.example.com). - Confirm you added a CNAME record (not an A record) for subdomains.
- If you're on Cloudflare, set the proxy to DNS only (gray cloud) for both records.
- 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.comOne non-obvious thing worth knowing: even after dig shows your records resolving, the dashboard can still report "Pending" for up to 30 minutes. The verifier sits behind upstream resolvers that cache negative DNS responses, and that cache window has to age out before re-checking succeeds. If everything resolves locally but the dashboard hasn't updated, give it half an hour before assuming a deeper problem.
DNS Troubleshooting covers provider-specific gotchas.
GitHub Repository Not Appearing
If your repo isn't in the list when you create a project, the Jamdesk GitHub App likely isn't installed on the repo's organization, or repository access is set to "Selected repositories" without yours included. Re-authorize at github.com/settings/installations and grant access to either "All repositories" or the specific repo you need.
See GitHub Issues for webhook and permission problems.
Analytics Data Missing
A few common reasons your dashboard shows zero visitors. Analytics take up to 24 hours to appear after a site's first deploy, so brand-new projects look empty for a while. Ad blockers and Do Not Track stop a chunk of visits from being counted — your numbers will always trail your server logs. If neither of those applies, confirm your site is actually deployed and publicly accessible.
Analytics Issues goes deeper on delayed or missing data.
Login Problems
Can't sign in, or getting bounced back to the login screen? Clear cache and cookies for dashboard.jamdesk.com, then try an incognito window. If you sign in with GitHub, your GitHub email needs to match the email on your Jamdesk account.
See Login Issues for account recovery steps.