How to Fix Ruby DNS Resolution Errors When Using QGTunnel with Third-Party APIs

TL;DR: If you're using QGTunnel in transparent mode for database connections and seeing Socket::ResolutionError when calling unrelated APIs like Mailchimp, the fix is to disable transparent mode and connect to your database via localhost instead.

The Problem

You're running a Rails app on Heroku. You use QGTunnel to route your database traffic through QuotaGuard's static IPs so you can connect to an IP-allowlisted AWS RDS instance. Everything works great.

Then you add a new API integration. Maybe Mailchimp. Maybe Stripe. Maybe any third-party service. You're not even trying to proxy this traffic through QuotaGuard. But when you make the API call, you get this error:

/app/vendor/bundle/ruby/3.3.0/gems/excon-0.112.0/lib/excon/socket.rb:390:in `unpack_sockaddr_in': 
getnameinfo: Result too large for supplied buffer (Socket::ResolutionError) (Excon::Error::Socket)

The API call works fine in development. It works on any Heroku dyno that doesn't use QGTunnel. But the moment QGTunnel is wrapping your process, third-party API calls fail with DNS resolution errors.

Why This Happens

When you configure QGTunnel with transparent mode enabled, the tunnel configuration looks something like this:

{
  "Tunnels": {
    "0": {
      "accept": "127.0.0.1:5432",
      "connect": "your-database.cluster-xyz.us-east-1.rds.amazonaws.com:5432",
      "transparent": true,
      "encrypted": false
    }
  }
}

That "transparent": true setting is the key. In transparent mode, QGTunnel installs a DNS override mechanism so it can intercept hostname lookups for your configured tunnel destinations. This lets your app connect to your RDS hostname directly while QGTunnel silently routes the traffic through the proxy.

The problem is that this DNS override can interfere with how certain Ruby libraries perform name resolution. The Excon HTTP library (used by the Mailchimp Ruby SDK and many others) is particularly sensitive to this. Even though Mailchimp's hostname isn't being tunneled, the DNS override mechanism affects how Ruby resolves all hostnames during that process.

The Solution

Stop using transparent mode. Instead, connect to your database via localhost and let QGTunnel forward the traffic.

Step 1: Update Your Database Configuration

Change your database.yml to connect to 127.0.0.1 on port 5432:

production:
  adapter: postgresql
  host: 127.0.0.1
  port: 5432
  database: your_database
  username: <%= ENV['DATABASE_USERNAME'] %>
  password: <%= ENV['DATABASE_PASSWORD'] %>

If you're using DATABASE_URL, you'll need to construct a localhost-based URL instead of pointing at the RDS hostname directly.

Step 2: Update Your QGTunnel Configuration

In your QuotaGuard dashboard, navigate to Settings → Setup → Tunnel and update your tunnel configuration:

The key change is setting Transparent to false.

Step 3: Disable QGTunnel DNS Overrides

Set an environment variable to explicitly disable the DNS override mechanism:

heroku config:set QGTUNNEL_DNSMODE=DISABLED -a your-app-name

Step 4: Restart Your App

heroku restart -a your-app-name

Step 5: Test

Run your API call again. The Socket::ResolutionError should be gone, and your database connection still works because QGTunnel is forwarding traffic from localhost:5432 to your RDS instance through the proxy.

How It Works After the Fix

With transparent mode disabled, here's what happens:

1. Your Rails app connects to 127.0.0.1:5432
2. QGTunnel is listening on that local port
3. QGTunnel forwards the connection through QuotaGuard's SOCKS5 proxy to your RDS instance
4. Your RDS firewall sees traffic from QuotaGuard's static IP and allows it

Meanwhile, your Mailchimp, Stripe, and other API calls resolve DNS normally without any interference from QGTunnel's override mechanism.

When to Use Transparent Mode

Transparent mode is convenient when you have existing code that hardcodes database hostnames and you can't easily change the connection string. It lets QGTunnel intercept connections to specific hostnames without modifying your application configuration.

But if you're seeing DNS resolution errors in unrelated parts of your application, the tradeoff isn't worth it. Switching to localhost connections with transparent mode disabled gives you the same database proxying without the side effects.

Quick Reference

If you're hitting this issue, the fix takes about 5 minutes. Update your database config to use localhost, flip transparent mode to false in the QuotaGuard dashboard, set the environment variable, and restart.

Need Help?

If you're still seeing issues after making these changes, reach out to support@quotaguard.com with:

1. Your QGTunnel debug output (QGTUNNEL_DEBUG=true)
2. The exact error message
3. Which Ruby HTTP library is failing (Excon, Net::HTTP, Faraday, etc.)

We'll help you get it sorted.

This post is based on a real customer case from January 2026. Thanks to the team at Inside Out Box for working through the debugging with us.