Troubleshooting
Fix common tpaw connection errors, startup issues, and query problems with this error reference table.
Most tpaw issues stem from connection configuration or network access. This page covers the most common errors and their solutions.
Connection error reference
| Error | Likely cause | Fix |
|---|---|---|
Connection refused | PostgreSQL not running, wrong port | Verify PostgreSQL is running: pg_isready -h host -p port. Check port (default 5432). |
password authentication failed for user "..." | Wrong username or password | Double-check credentials. If using peer auth, ensure username matches your OS user. |
database "..." does not exist | Database name typo or database not created | Leave the Database field blank to connect to the default DB, or check the name with \l in psql. |
SSL connection required | Server requires SSL, form has SSL disabled | Set SSL mode to Require in the connection form. |
SSL SYSCALL error: EOF detected | SSL mismatch or network issue | Try setting SSL mode to Disable if your server doesn't use SSL, or Require if it does. |
could not translate host name "..." to address | DNS resolution failure | Use the IP address instead of a hostname, or check your DNS/hosts file. |
Connection timed out | Firewall blocking port 5432, wrong host | Check that port 5432 is open on the server's firewall. For cloud databases, check allowed IPs. |
FATAL: role "..." does not exist | Username doesn't exist in PostgreSQL | Create the role: CREATE ROLE username WITH LOGIN PASSWORD 'pw'; |
FATAL: too many connections | Max connection limit reached | Increase max_connections in postgresql.conf or use a connection pooler (PgBouncer). |
SSH tunnel: connection refused | Bastion host not reachable or SSH port wrong | Verify you can SSH to the bastion manually: ssh user@bastion-host. Check SSH port (default 22). |
SSH tunnel: authentication failed | Wrong SSH key or password | Check your SSH key path. Ensure the key is added to ~/.ssh/authorized_keys on the bastion. |
pg_dump not found | pg_dump not installed at expected path | Install PostgreSQL client tools: brew install postgresql on macOS. |
tpaw won't launch
Symptom: tpaw bounces in the Dock but doesn't open.
Fix: Check Console.app for crash logs filtered by "tpaw". If you see a code signature error, re-download from the releases page. If the issue persists, delete the app preferences:
Autocomplete shows wrong schema
Symptom: Autocomplete suggests columns from a different connection.
Fix: This can occur if you switch connections rapidly. Close and reopen the Query Editor tab to refresh the schema cache for the active connection.
Query results seem stale
Symptom: The Data Grid shows old data after an external change.
Fix: Press Cmd+R to refresh the current view. You can also right-click the table in the sidebar and choose Refresh.
Getting more help
- Check the tpaw GitHub issues for known bugs
- Include the PostgreSQL error code (e.g.,
08006,28P01) when reporting issues — it's shown in the error banner