PostgreSQL Proxy - Client Error Reference

​

Error format

​

Error severity levels

​

Error categories

​

Authentication and authorization errors

​

SSL/TLS required

• Severity: FATAL
• Code: 28000 (invalid_authorization_specification)
• Message: “SSL connection is required”
• Hint: “Use sslmode=require or connect with SSL enabled”
• When: Client attempts unencrypted connection when TLS is mandatory
• Resolution: Configure client to use SSL/TLS (e.g., sslmode=verify-full in connection string)

​

Invalid user format

• Severity: FATAL
• Code: 28000 (invalid_authorization_specification)
• Message: “invalid user format: username must include branch (e.g., user.branch)”
• When: Username doesn’t follow required format for branch routing
• Resolution: Include branch identifier in username (format: username.branchname)

​

Authentication failure

• Severity: FATAL
• Code: 28P01 (invalid_password)
• Message: Various authentication-specific messages
• When: Password validation fails
• Resolution: Verify credentials are correct

​

Connection and network errors

​

Startup message errors

• Severity: FATAL
• Code: 08006 (connection_failure)
• Messages:
  • “failed to read startup message”
  • “startup message too short: %d bytes”
  • “incomplete startup message: expected %d bytes, got %d”
  • “failed to parse startup header”
• When: Initial connection handshake fails
• Resolution: Likely a client library bug - check for driver updates

​

Backend connection failures

• Severity: FATAL
• Code: 08006 (connection_failure)
• Messages:
  • “failed to connect to upstream”
  • “failed to send startup message”
  • “failed to setup backend”
  • “connection retry timeout - branch %s unavailable after %s”
• When: Proxy cannot establish connection to backend database
• Resolution: Retry with exponential backoff - this is often transient

​

Routing and branch resolution errors

​

Branch not found

• Severity: FATAL
• Code: 28000 (invalid_authorization_specification)
• Message: “branch %s does not exist”
• When: Specified branch identifier is not recognized
• Resolution: Verify branch name is correct

​

Member not found

• Severity: FATAL
• Code: 28000 (invalid_authorization_specification)
• Message: “member %s not found in branch %s”
• When: Specific database member requested doesn’t exist
• Resolution: Check member name and branch configuration

​

No primary available

• Severity: FATAL
• Code: 08006 (connection_failure)
• Message: “no primary available for branch %s”
• When: Primary database instance is unavailable
• Resolution: Database outage - retry with exponential backoff

​

No replica available

• Severity: FATAL
• Code: 08006 (connection_failure)
• Message: “no replica available for branch %s”
• When: No read replicas are available for the branch
• Resolution: All replicas are down - retry with exponential backoff

​

No running members

• Severity: FATAL
• Code: 08006 (connection_failure)
• Message: “no running members available for branch %s”
• When: All database instances in branch are down
• Resolution: Total database outage - retry, but investigate the cause as this indicates all instances are down

​

Pooler restriction

• Severity: FATAL
• Code: 28000 (invalid_authorization_specification)
• Message: “pooler only supports primary destinations for branch %s”
• When: Attempting to use pooler with non-primary target
• Resolution: Connect to replicas via port 5432 instead of 6432 (pgbouncer port doesn’t support replicas)

​

SQLSTATE error codes

​

Client library considerations

​

Connection retry logic

• Errors with code 08006 are typically transient and safe to retry
• Errors with code 28000 or 28P01 indicate configuration issues - don’t retry without changes

​

Error handling best practices

1. Always check the SQLSTATE code, not just the message text
2. Implement exponential backoff for connection failures (08006)
3. Handle shutdown notices gracefully by proactively reconnecting
4. Log full error details including severity and code for debugging

​

Need help?