PostgreSQL Proxy - Client Error Reference

August 13, 2025

This document provides a comprehensive reference of all error messages that the Exosphere PostgreSQL proxy may send to clients. These errors follow the PostgreSQL wire protocol format and include standard SQLSTATE error codes.

Error format

All errors sent by Exosphere follow the PostgreSQL ErrorResponse message 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 (psbouncer port doesn't support replicas)

SQLSTATE error codes

Exosphere uses standard PostgreSQL SQLSTATE codes for compatibility:

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?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.