From 0ee62fdc4711bbca1fb1c19cb33f627164d599d1 Mon Sep 17 00:00:00 2001 From: Jason Date: Thu, 9 Apr 2026 16:11:10 +0200 Subject: [PATCH] Add HyperSync troubleshooting docs for DNS resolution issues 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 --- docs/HyperSync/hypersync-troubleshooting.md | 142 ++++++++++++++++++++ sidebarsHyperSync.js | 1 + 2 files changed, 143 insertions(+) create mode 100644 docs/HyperSync/hypersync-troubleshooting.md diff --git a/docs/HyperSync/hypersync-troubleshooting.md b/docs/HyperSync/hypersync-troubleshooting.md new file mode 100644 index 00000000..58ca8c75 --- /dev/null +++ b/docs/HyperSync/hypersync-troubleshooting.md @@ -0,0 +1,142 @@ +--- +id: hypersync-troubleshooting +title: Troubleshooting +sidebar_label: Troubleshooting +slug: /troubleshooting +description: Solutions for common HyperSync and HyperRPC connectivity issues including DNS resolution failures. +--- + +# HyperSync Troubleshooting + +This guide covers common connectivity issues with HyperSync and HyperRPC endpoints. If you don't find a solution here, please join our [Discord community](https://discord.gg/DhfFhzuJQh) for additional support. + +## DNS Resolution Failures + +### Symptoms + +- HyperSync or HyperRPC requests hang or timeout intermittently +- `curl` to HyperSync endpoints is slow on the first request but works after retrying +- Errors like `Could not resolve host` or `SERVFAIL` when querying `*.hypersync.xyz` or `*.rpc.hypersync.xyz` +- The issue appears on cold start (first request after a period of inactivity) but resolves after a successful lookup + +### Cause + +HyperSync and HyperRPC endpoints use geographic load balancing (GSLB) with a multi-step DNS delegation chain. Some ISP and home router DNS resolvers — particularly in regions like South Africa, parts of Asia, and other areas far from US/EU — cannot follow this delegation chain correctly and return `SERVFAIL` instead of resolving the domain. + +The issue is made worse by the low TTL (time-to-live) on DNS records, which means your resolver needs to re-resolve the full chain frequently rather than serving from cache. + +**This is a client-side DNS resolver issue, not a HyperSync service outage.** Public DNS resolvers like Cloudflare and Google handle the resolution correctly. + +### How to verify + +You can confirm this is a DNS issue by testing with different resolvers: + +```bash +# This will likely fail or be slow (your system/ISP resolver) +dig eth.hypersync.xyz A + +# These should succeed immediately +dig eth.hypersync.xyz A @1.1.1.1 # Cloudflare +dig eth.hypersync.xyz A @8.8.8.8 # Google +``` + +If the first command returns `status: SERVFAIL` but the others return `status: NOERROR` with IP addresses, your system DNS resolver is the problem. + +### Solution + +Configure your system to use public DNS resolvers (Cloudflare and Google) instead of your ISP/router DNS. + +#### Linux (systemd-resolved — Ubuntu, Debian, Fedora, etc.) + +```bash +sudo mkdir -p /etc/systemd/resolved.conf.d + +echo '[Resolve] +DNS=1.1.1.1 8.8.8.8 1.0.0.1 8.8.4.4 +FallbackDNS=9.9.9.9 +Cache=yes +CacheFromLocalhost=yes' | sudo tee /etc/systemd/resolved.conf.d/dns.conf + +sudo systemctl restart systemd-resolved +``` + +To revert: + +```bash +sudo rm /etc/systemd/resolved.conf.d/dns.conf +sudo systemctl restart systemd-resolved +``` + +#### macOS + +```bash +# Replace Wi-Fi with your network interface name if different +sudo networksetup -setdnsservers Wi-Fi 1.1.1.1 8.8.8.8 1.0.0.1 8.8.4.4 +``` + +To revert: + +```bash +sudo networksetup -setdnsservers Wi-Fi Empty +``` + +#### Windows + +1. Open **Settings > Network & Internet > Wi-Fi > Hardware properties** +2. Click **Edit** next to DNS server assignment +3. Set to **Manual** and enter: + - Preferred DNS: `1.1.1.1` + - Alternate DNS: `8.8.8.8` + +#### Docker containers + +If running HyperSync clients inside Docker, add DNS configuration to your container or compose file: + +```yaml +# docker-compose.yml +services: + your-service: + dns: + - 1.1.1.1 + - 8.8.8.8 +``` + +### DNS resolvers reference + +| IP | Provider | Notes | +|---|---|---| +| `1.1.1.1` / `1.0.0.1` | Cloudflare DNS | Generally the fastest global resolver | +| `8.8.8.8` / `8.8.4.4` | Google Public DNS | Reliable with good global coverage | +| `9.9.9.9` | Quad9 | Privacy-focused, blocks known malicious domains | + +## Connection Timeouts + +### Symptoms + +- Requests to HyperSync endpoints timeout after DNS resolves successfully +- `curl https://.hypersync.xyz/height` hangs or returns a connection error + +### Possible causes + +1. **Firewall or corporate network blocking:** Some corporate or university networks block non-standard traffic. Try from a different network to confirm. +2. **Regional routing issues:** In rare cases, network routing between your region and the HyperSync servers may be degraded. This is typically transient. + +### How to verify + +```bash +# Check if the endpoint is reachable +curl -v --max-time 10 https://eth.hypersync.xyz/height + +# Check latency to the resolved IP +ping -c 5 $(dig +short eth.hypersync.xyz A @1.1.1.1 | head -1) +``` + +If `curl` succeeds with a block height number, the service is healthy and the issue is likely on the network path between you and the server. + +## Getting Help + +If you're still experiencing issues after trying the above solutions: + +1. Run the DNS check commands above and note the output +2. Note your geographic location and ISP +3. Share these details in our [Discord community](https://discord.gg/DhfFhzuJQh) so we can help debug further diff --git a/sidebarsHyperSync.js b/sidebarsHyperSync.js index cc30a323..b537e70a 100644 --- a/sidebarsHyperSync.js +++ b/sidebarsHyperSync.js @@ -24,6 +24,7 @@ module.exports = { // "HyperRPC/hyperrpc-supported-networks", // ], // }, + "hypersync-troubleshooting", { type: "category", label: "HyperFuel",