Authentication errors show encoding errors instead of auth errors

[dev-exsis]

Summary

The postgres library (version 3.5.6) incorrectly throws FormatException: Missing extension byte (at offset 10) when authentication fails, instead of showing a clear authentication error message.

Expected Behavior

• Invalid password → Clear error: "Password authentication failed" or "Invalid password"
• User doesn't exist → Clear error: "User does not exist"

Actual Behavior

• Invalid password → Confusing error: FormatException: Missing extension byte (at offset 10)

Steps to Reproduce

1. Create a connection with incorrect password:

final endpoint = Endpoint(
  host: 'localhost',
  port: 5432,
  database: 'testdb',
  username: 'postgres',
  password: 'wrong_password', // Incorrect password
);

final connection = await Connection.open(endpoint, settings: ConnectionSettings(sslMode: SslMode.disable));

2. The library throws:

Severity.error Socket error: FormatException: Missing extension byte (at offset 10)

Root Cause Analysis

The issue occurs in the authentication flow:

1. PostgreSQL Authentication Flow:

   Client → Sends credentials
   Server → Responds with authentication method
   Client → Processes server response
   

2. Where the Bug Occurs:

   • PostgreSQL server responds with an authentication error message
   • The postgres library tries to decode this response as UTF-8
   • But the server response is not a valid UTF-8 string
   • Result: FormatException: Missing extension byte

3. Why Offset 10:

   • The first bytes of PostgreSQL response contain protocol information
   • Offset 10 indicates the error is in the first bytes of the response
   • The library is trying to interpret binary data as UTF-8 text

Comparison with Other Libraries

Libraries that work correctly:

• psql (official client): Shows "password authentication failed"
• DBeaver: Shows "FATAL: password authentication failed"
• Python psycopg2: Shows clear authentication error

postgres Dart 3.5.6:

• Shows encoding error instead of authentication error

Impact

1. Difficult Debugging: Developers waste time investigating encoding issues instead of checking credentials
2. Poor UX: Users see technical errors instead of clear messages
3. Confusion: Appears to be a configuration problem when it's just a wrong password

Environment

• Library Version: postgres 3.5.6
• Dart Version: 3.8.1
• Platform: Windows 10
• PostgreSQL Version: 15.x

Suggested Solutions

1. Proper Error Handling: Catch authentication errors before attempting UTF-8 decoding
2. Protocol Parsing: Correctly parse PostgreSQL protocol messages
3. Fallback Error Messages: Provide clear authentication error messages

Workaround

try {
  final connection = await Connection.open(endpoint, settings: settings);
} catch (e) {
  if (e.toString().contains('Missing extension byte')) {
    // Likely authentication error
    throw Exception('Authentication error: please check username and password');
  }
  rethrow;
}

Files Affected

• lib/src/v3/connection.dart (line 1240)
• _AuthenticationProcedure class

This bug makes debugging authentication issues unnecessarily difficult and should be fixed to provide clear, actionable error messages.

---

You can copy this and paste it directly into a GitHub issue for the postgres library repository.

[isoos]

@dev-exsis: I'm curious: would you be able to create a test case for it, so that the fix is easily verified?