Skip to content

Troubleshooting

Common issues and solutions when using pg.

Connection Issues

Service Not Found

error: definition of service "production" not found
Solution: Check your ~/.pg_service.conf file exists and contains the service: 
cat ~/.pg_service.conf

Connection Refused

error: connection to server at "[name]" ([IP]), port [port] failed: Connection refused
Solutions:

  • Check PostgreSQL is running: pg info ready -s production
  • Verify host/port in service file
  • Check firewall settings
  • Check pg_hba configuration

Comprehensive Connection Troubleshooting

For a complete visual guide to diagnosing PostgreSQL connection issues, see Can't Connect to PostgreSQL?

Authentication Failed

error: connection to server failed: FATAL: password authentication failed
Solutions:

  • Set up or check .pgpass file for passwords
  • Use certificate authentication
  • Check username in service file

Command Issues

Unknown Command

Error: Unknown command: xyz.
Solution: Use pg help to see available commands.

Mixed Connection Methods

[ERROR] Service (-s) cannot be used with individual connection parameters
or 
[ERROR] Connection string (-c) cannot be used with other connection options
Solution: Use only one connection method at a time: 
# ❌ Don't mix
pg query -s production -h localhost

# ✅ Use one method
pg query -s production

Argument Order

Commands fail silently or with unexpected errors.

Solution: Put connection options before tool options: 

# ❌ Wrong order
pg dump db dump.sql -s production

# ✅ Correct order  
pg dump db -s production dump.sql

Flag Conflicts

FATAL:  database "[query]" does not exist
Problem: Using -c for commands when -c is reserved for connection strings.

Solution: Use long form flags that conflict: 

# ❌ Conflicts with connection string flag
pg query -s production -c "select version();"

# ✅ Use long form
pg query -s production --command "select version();"

Debugging

Enable Debug Logging

pg query -s production --pg-verbose

Test Commands Without Execution

pg dump db -s production --pg-dry-run -f dump.sql
# Ouput: Would execute: pg_dump -d 'service=production' -f dump.sql

Common Gotchas

File Permissions

If pg won't run: 

chmod +x /usr/local/bin/pg

PostgreSQL Tools Missing

Command 'pg_dump' not found
Solution: Install PostgreSQL client tools: 
# Ubuntu/Debian
sudo apt install postgresql-client

# macOS
brew install postgresql

Service File Location

Service file not found on some systems.

Solution: Check these locations:

  • ~/.pg_service.conf (user-specific)
  • /etc/postgresql-common/pg_service.conf (system-wide on Debian/Ubuntu)

Getting Help

  • pg help - Show all commands
  • pg <command> --help - Show command-specific help
  • pg <command> <subcommand> --help - Show tool-specific help
  • pg <command> --pg-verbose - Debug connection issues
  • pg <command> --pg-dry-run - See what would be executed

Still having issues? Check the PostgreSQL documentation for underlying tool problems.