GitHub Pages Custom Domain Troubleshooting: Unpacking `NotServedByPagesError` and DNS Verification Challenges

Setting up a custom domain for your GitHub Pages site should be straightforward, but sometimes, developers encounter persistent issues like the dreaded NotServedByPagesError, failed domain ownership verification, and SSL certificate problems. This community insight dives into a common scenario where a seemingly correct DNS configuration still results in GitHub Pages reporting errors.

The GitHub Pages Custom Domain Conundrum

A developer recently reported a puzzling situation: their GitHub Pages site, hosted on biggerworldspodcast.com, was correctly configured with GitHub's recommended A records and a WWW CNAME. The site was even serving content over HTTP, and deployments were successful. Yet, GitHub Pages stubbornly reported:

DNS check unsuccessful
Both biggerworldspodcast.com and its alternate name are improperly configured.
Domain does not resolve to the GitHub Pages server.
(NotServedByPagesError)

Adding to the confusion, domain ownership verification also failed, despite the required TXT record being publicly available from the authoritative nameservers. The developer confirmed this with a dig command:

dig @alfred.ns.cloudflare.com _github-pages-challenge-lorigoldman721.biggerworldspodcast.com TXT +short
Result: "696e2110d1aa79ffe5caad6f67ea06"

The final symptom was an SSL_ERROR_BAD_CERT_DOMAIN, indicating that the site was presenting GitHub's default *.github.io certificate instead of one for the custom domain.

Understanding the Root Cause: DNS Propagation vs. GitHub's Validation

The key to understanding these issues lies in the difference between how a browser resolves DNS and how GitHub's automated validation processes work, especially after recent DNS changes. When a user visits your site, their browser queries DNS, eventually hitting your authoritative nameservers (e.g., Cloudflare's). If these records are correct, the request routes to GitHub's servers, which then serve your site because your repository's CNAME file matches.

However, GitHub's background validation loops operate differently. They query global public DNS resolvers (like Google DNS or Cloudflare 1.1.1.1), which rely on caching. If nameservers or DNS records were recently changed (as they were in this case, on October 30), these public resolvers might still hold stale or negative cached responses. This delay in global DNS propagation means GitHub's validation bot sees an outdated state, leading to:

• NotServedByPagesError: The bot interprets stale DNS data as an incorrect configuration.
• Failed TXT Verification: Similarly, the ownership verification engine queries public resolvers, which might not yet have the newly published TXT record.
• SSL Certificate Issues: GitHub will not attempt to issue or bind a Let's Encrypt SSL certificate for your custom domain until both the primary DNS and domain ownership checks successfully clear. The *.github.io certificate is a fallback.

Essentially, the problem isn't a misconfiguration on your end, but a timing issue related to global DNS cache expiration.

The Solution: Patience and Proactive Re-verification

Resolving these issues requires a combination of patience and specific re-verification steps:

1. Allow Full DNS Propagation (24–48 Hours): Since nameserver changes can take time to propagate globally, give DNS caches up to 48 hours to fully expire and update. This is crucial for GitHub's validation bots to see the correct records.

2. Force Re-verification in GitHub Settings: Once you've allowed sufficient propagation time, you can prompt GitHub to re-check the domain. Navigate to your Account / Organization Settings ➔ Pages ➔ Verified domains. Locate your custom domain (e.g., biggerworldspodcast.com) and click Continue verifying or Check again. This action forces GitHub to bypass its internal cache and re-query public DNS resolvers.

3. Verify in Repository Settings: After the domain is successfully verified at the user/organization level, go to your repository's Settings ➔ Pages section. Re-save your custom domain there. This step often triggers the final checks and certificate provisioning.

Once these DNS checks pass, the Enforce HTTPS checkbox in your repository settings will become clickable, and GitHub will proceed to issue and bind the Let's Encrypt TLS certificate for your custom domain, resolving the SSL error. By understanding these nuances, developers can more efficiently troubleshoot GitHub Pages custom domain issues, ensuring their projects are accessible and secure, which ultimately contributes to better overall GitHub statistics and project visibility.