risingwavelabs/risingwave · error · PsqlError

Protocol violation

Error message

Protocol violation: {0}

What it means

pgwire wraps a ProtocolViolationError into PsqlError::ProtocolError with this display message. It is thrown when the client sends messages that violate the PostgreSQL wire protocol: wrong message order, malformed message bodies, or unsupported/unexpected message types for the current protocol state.

Solutions

  1. Check the ProtocolViolationError source for the offending message code or detail.
  2. Use a supported, up-to-date PostgreSQL client driver for your language.
  3. Remove or debug any proxy/middleware between the client and RisingWave that may alter the byte stream.
  4. Compare the client's protocol version and message flow with the PostgreSQL wire protocol spec.

Example fix

// before: sending messages in wrong state
conn.send(Parse { .. }); // before startup acknowledged
// after: await ready state before extended-protocol messages
conn.wait_ready().await?;
conn.send(Parse { .. })?;
Defensive patterns

Strategy: try-catch

Validate before calling

// use a spec-compliant driver and default protocol settings; avoid raw protocol hacks
assert!(driver_supports_pg_protocol_version(3));

Type guard

fn is_protocol_error(e: &PsqlError) -> bool { matches!(e, PsqlError::ProtocolError(_)) }

Try / catch

match session.run().await {
    Err(e @ PsqlError::ProtocolError(v)) => { log::error!("protocol violation: {e} (detail: {v})"); fail_fast_no_retry(); }
    other => other,
}

Prevention

When it happens

Trigger: The pgwire parser encounters an invalid message type/code, a malformed body, or a message not allowed in the current state (e.g. Parse/Bind before Startup completes, invalid Copy data framing).

Common situations: Buggy or non-standard client drivers/libraries; custom scripts speaking raw wire protocol; middleware/proxies mangling the stream; protocol version mismatch between client and server.

Related errors

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/8f028e4946a5a5ba. Report an issue: GitHub.

Appendix: source

Thrown at src/utils/pgwire/src/error.rs:37

use thiserror::Error;

use crate::pg_server::BoxedError;
pub type PsqlResult<T> = std::result::Result<T, PsqlError>;

/// Error type used in pgwire crates.
#[derive(Error, Debug)]
pub enum PsqlError {
    #[error("Failed to start a new session: {0}")]
    StartupError(
        #[source]
        #[backtrace]
        BoxedError,
    ),

    #[error("Invalid password")]
    PasswordError,

    #[error("Protocol violation: {0}")]
    ProtocolError(
        #[source]
        #[backtrace]
        ProtocolViolationError,
    ),

    #[error("Failed to run the query: {0}")]
    SimpleQueryError(
        #[source]
        #[backtrace]
        BoxedError,
    ),

    #[error("Failed to prepare the statement: {0}")]
    ExtendedPrepareError(
        #[source]
        #[backtrace]
        BoxedError,

View on GitHub (pinned to 6469eb736d)