Troubleshooting DNS Resolution Issues

When connecting to your database or service, Portable first needs to resolve the hostname you provided to an IP address. If this step fails, you'll see a "DNS Resolution" error in the diagnostic checks.

What This Means

Your hostname (e.g., db.example.com) couldn't be resolved to an IP address. This typically happens before any actual connection attempt is made.

Common Causes

1. Typo in the Hostname

The most common cause. Double-check for:

• Misspellings (databse.example.com instead of database.example.com)
• Wrong domain (db.example.com vs db.example.io)
• Extra or missing characters

2. Private/Internal Hostname

If your database uses an internal DNS name (e.g., db.internal.mycompany.local), it won't resolve from Portable's servers. Internal DNS names only work within your private network.

Solution: Use one of these instead:

• A public DNS name that resolves to your server
• The public IP address directly
• Set up a bastion host with SSH tunneling

3. DNS Propagation Delay

If you recently created or changed a DNS record, it may take time to propagate (anywhere from minutes to 48 hours, depending on TTL settings).

Solution: Wait and retry, or verify the record has propagated using a tool like dnschecker.org.

4. DNS Server Issues

Your DNS provider may be experiencing issues, or the DNS record may have been deleted.

How to Diagnose

Verify the hostname resolves publicly

From your local machine, run:

# macOS/Linux
nslookup db.example.com
# or
dig db.example.com

# Windows
nslookup db.example.com

If this returns an IP address, the hostname is valid. If it fails locally too, the issue is with the DNS record itself.

Check from an external source

Use an online DNS lookup tool to verify the hostname resolves from outside your network:

• Google DNS Lookup
• MXToolbox DNS Lookup

For cloud databases

If you're using a managed database service, find the correct endpoint in your cloud console:

Provider	Where to Find
AWS RDS	RDS Console → Databases → Your DB → Endpoint
Google Cloud SQL	Cloud Console → SQL → Your Instance → Connect → Public IP or Connection name
Azure Database	Azure Portal → Your Database → Overview → Server name

Quick Fixes

1. Use an IP address - If you have a static public IP, use it directly instead of a hostname
2. Check your cloud console - Copy the endpoint directly from your database provider's dashboard
3. Use SSH tunnel - If your database is on a private network, configure an SSH tunnel through a bastion host that Portable can reach

Still Stuck?

If the hostname resolves correctly from external tools but Portable still reports a DNS error, contact support with:

• The exact hostname you're using
• The output of dig <hostname> or nslookup <hostname>
• Your source/destination ID from Portable