Connection failures

When Quay can’t connect, the error dialog shows the engine’s raw error message plus a Quay-side classification + suggested fix. The classifier covers the common cases below.

”Could not resolve host” / DNS failure

The hostname doesn’t resolve.

• VPN required? Most prod hosts are private. Connect to the corporate VPN first and retry.
• DNS propagation for a brand-new host — check dig <host> in a terminal; if it returns NXDOMAIN, the host literally doesn’t exist (yet).
• Local hosts entry — if the host is in /etc/hosts, Quay respects it (Quay uses the OS resolver).

”Connection refused”

DNS resolved, but the host actively rejected the TCP connection.

• Wrong port — PG defaults to 5432, MySQL to 3306, MSSQL to 1433, Mongo to 27017, Redis to 6379. Check the engine’s listener.
• Listener not running — ssh user@host && systemctl status postgresql (or equivalent).
• Firewall — cloud providers block all inbound by default. Check the security group / firewall rule for your IP.

”Connection timed out”

DNS resolved, but no TCP response — usually a firewall silently dropping packets.

• Local firewall rules on your laptop blocking outbound — rare but possible (corporate-managed Macs sometimes).
• VPN required — same as DNS issues.
• Cloud security group missing your IP. Whitelist your current IP (curl ifconfig.me).

TLS failures

”self-signed certificate”

The DB’s cert isn’t signed by a CA in your trust store. Three options:

• Add the CA to your local trust — preferred for prod certs from internal CAs. macOS: security add-trusted-cert. Linux: update-ca-certificates.
• Provide the CA file in Quay — connection edit → SSL/TLS → CA cert path → point at the PEM. Quay validates against that CA only, not your system trust.
• Set sslmode=verify-ca (PG) or tls_insecure=true (MySQL / Mongo) — Quay supports it for dev only; production connections should never disable verification.

”hostname verification failed”

The cert’s SAN doesn’t match the hostname you’re connecting to. Common when connecting to a Cloud SQL public IP rather than the Cloud SQL hostname; or when there’s a load-balancer with a different hostname than the DB cert.

Either connect to the cert’s hostname, or set sslmode=verify-ca to skip hostname check while still verifying the CA.

Auth failures

”FATAL: password authentication failed”

Wrong password. Or wrong user. Or the user doesn’t have pg_hba.conf access from your IP. Test from the command line:

psql "host=db.example.com user=app dbname=app sslmode=require"

If psql works but Quay doesn’t: paste the URI string into Quay’s “connection URI” field rather than filling fields individually. Some auth methods (Trust, Peer, GSSAPI) only work with specific URI flags.

”Access denied for user ‘X’@‘IP’”

MySQL: the user can authenticate as app@'%' but not from your specific IP if the user is bound to a hostname.

SELECT user, host FROM mysql.user WHERE user = 'app';

Either grant app@'<your IP>' or change to app@'%'.

”ECONNRESET” mid-query

Something killed the TCP connection. Common causes:

• Idle timeout — most cloud DBs (Cloud SQL, RDS) close idle connections after 5–10 minutes. Quay’s connection pool reconnects automatically; if you see ECONNRESET, run the query again.
• MITM proxy — corporate TLS-inspecting proxies sometimes drop mid-flight. Add the proxy’s CA to your trust store.

SSH tunnel failures

See SSH tunnels for the full list. Quick recap:

• permission denied (publickey) — key file or agent issue
• host key verification failed — bastion’s key changed
• connection timed out — bastion not reachable
• too many authentication failures — agent has too many keys; pin to one with IdentitiesOnly yes

Driver-specific weirdness

MongoDB: “no primary in topology”

The replica-set member you connected to isn’t currently primary. Use the full SRV URI (mongodb+srv://…) rather than a single host — the driver auto-discovers the primary.

Redis: “WRONGTYPE Operation against a key holding the wrong kind of value”

You’re using the wrong viewer for the key’s type. Quay’s Redis browser auto-detects type per key; if you’ve cached a stale type (e.g. you deleted + recreated as a different type), refresh the browser.

Cassandra: “no host available”

Either no contact point resolves, or the cluster’s auth is wrong, or the data center name in local_dc doesn’t match. Cassandra’s error message is usually unhelpful; check nodetool status on the cluster.

Still failing

Open Settings → About → “Copy diagnostic bundle”. That gives you a JSON file with the connection profile (credentials redacted), the last 3 attempts’ raw error messages, and your Quay version + OS. Email it to zaid.ug@gmail.com.