protocol_violation malformed OAUTHBEARER message — 08P01

Symptoms

A statement failed with SQLSTATE 08P01 (protocol_violation), reported at severity ERROR. This is a Connection Exception condition: PostgreSQL emits the message malformed OAUTHBEARER message.

• The client receives SQLSTATE 08P01 (protocol violation).
• The operation is rejected at ERROR level; the statement does not complete.
• The server adds a DETAIL line with specifics (see below).

What the server log shows

ERROR:  malformed OAUTHBEARER message
DETAIL:  Message did not contain a final terminator.

Why PostgreSQL raises this

Class 08 (Connection Exception) covers failures establishing or maintaining the client/server or replication connection. PostgreSQL raises it when the transport, handshake, or authentication channel breaks before or during a session.

As described in PostgreSQL’s Section 34.1 Database Connection Control Functions and Appendix A (PostgreSQL Error Codes), SQLSTATE 08P01 carries the condition name protocol_violation in class Connection Exception. (Paraphrased — see the linked reference for the exact wording.)

Common causes

• The server is down, restarting, or not listening on the expected host/port.
• A network device, firewall, or proxy dropped or refused the connection.
• TLS/GSS negotiation or the startup handshake failed.
• The session was terminated by the server or a timeout.

How to fix it

1. Confirm the server is up and accepting connections (pg_isready).
2. Verify host, port, and listen_addresses reachability.
3. Check firewalls, security groups, and any connection pooler in the path.
4. Inspect the server log around the disconnect for the underlying cause.

Version applicability

This message text is present in PostgreSQL 18, 19. It was introduced around PostgreSQL 18; earlier releases do not emit this exact text.

Related & next steps

• SQLSTATE 08P01 — Protocol Violation (full reference)
• PostgreSQL error code index

Reference: PostgreSQL Section 34.1 Database Connection Control Functions.