Skip to content

Add HyperSync DNS troubleshooting docs#860

Open
JasoonS wants to merge 1 commit intomainfrom
docs/hypersync-dns-troubleshooting
Open

Add HyperSync DNS troubleshooting docs#860
JasoonS wants to merge 1 commit intomainfrom
docs/hypersync-dns-troubleshooting

Conversation

@JasoonS
Copy link
Copy Markdown
Contributor

@JasoonS JasoonS commented Apr 9, 2026 •
edited by coderabbitai bot
Loading

Summary

  • Adds a new Troubleshooting page to the HyperSync docs covering DNS resolution issues
  • Documented root cause: ISP/router DNS forwarders in certain regions (South Africa, parts of Asia) return SERVFAIL when resolving HyperSync GSLB delegation chains
  • Includes verified fix (switching to Cloudflare/Google DNS) with instructions for Linux, macOS, Windows, and Docker
  • Added to HyperSync sidebar navigation

Context

Investigated intermittent DNS failures affecting all 90 HyperSync chain endpoints when accessed from South Africa. The issue was traced to consumer/ISP DNS resolvers being unable to follow the *.global.hypersync.xyz GSLB nameserver delegation. Switching to public resolvers (1.1.1.1 / 8.8.8.8) completely resolved the problem — verified with automated testing across all 180 endpoints.

Full technical report: https://github.com/enviodev/docs/blob/docs/hypersync-dns-troubleshooting/docs/HyperSync/hypersync-troubleshooting.md

Test plan

  • Verify the troubleshooting page renders correctly on the docs site
  • Confirm sidebar navigation includes the new page
  • Test the DNS verification commands in the docs are accurate

Summary by CodeRabbit

  • Documentation
    • Added troubleshooting guide for HyperSync/HyperRPC connectivity issues, including DNS resolution failures and connection timeouts with diagnostic steps and remediation solutions for all major operating systems.
    • Updated documentation navigation to include the new troubleshooting resource.

@JasoonS
Add HyperSync troubleshooting docs for DNS resolution issues
0ee62fd 
Users in certain regions (South Africa, parts of Asia) experience intermittent
DNS resolution failures when connecting to HyperSync and HyperRPC endpoints.
The root cause is that ISP/router DNS forwarders cannot follow the GSLB
delegation chain used by *.global.hypersync.xyz and *.rpc.hypersync.xyz.

This adds a troubleshooting page with:
- How to identify DNS resolution issues
- Verified fix: switching to public DNS resolvers (Cloudflare/Google)
- Platform-specific instructions (Linux, macOS, Windows, Docker)
- Connection timeout debugging guidance
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 9, 2026 •
edited
Loading

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 349774bd-2dd7-4ff7-a2c1-9d54dfd7d8e5

📥 Commits

Reviewing files that changed from the base of the PR and between cd9edca and 0ee62fd.

📒 Files selected for processing (2)
  • docs/HyperSync/hypersync-troubleshooting.md
  • sidebarsHyperSync.js
📝 Walkthrough

Walkthrough

A new HyperSync troubleshooting guide documentation page was added to provide users with diagnostic procedures for common connectivity issues such as DNS resolution failures and connection timeouts, including platform-specific remediation steps and guidance for obtaining support.

Changes

Cohort / File(s) Summary
HyperSync Troubleshooting Documentation
docs/HyperSync/hypersync-troubleshooting.md		 New comprehensive troubleshooting guide covering DNS resolution failures and connection timeouts, with diagnostic verification steps for Linux, macOS, Windows, and Docker environments, plus a "Getting Help" section.
Sidebar Configuration
sidebarsHyperSync.js		 Updated sidebar navigation to include the new hypersync-troubleshooting doc slug as a top-level entry.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

Suggested labels

codex

Poem

🐰 A troubleshooting tale, so clear and bright,
DNS woes and timeouts—now in sight!
With remedies for every platform's plight,
HyperSync users sleep sound at night! ✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately captures the main change: adding troubleshooting documentation for HyperSync, with specific focus on DNS issues as the primary problem being addressed.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/hypersync-dns-troubleshooting

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@vercel
Copy link
Copy Markdown

vercel bot commented Apr 9, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
envio-docs Ready Ready Preview, Comment Apr 9, 2026 2:14pm

Request Review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@JasoonS