risingwavelabs/risingwave · warning · PsqlError

Server throttled

Error message

Server throttled: {0}

What it means

PgwireError::ServerThrottle: the pgwire server is rate-limiting or rejecting incoming work (e.g. connection or query throttling limits reached) and reports the reason in the message. The client request was refused due to server-side load protection, not a SQL error.

Solutions

1. Read the payload string to identify which throttle was hit.
2. Reduce client concurrency/connection rate or add client-side backoff and retry with jitter.
3. Scale out frontend nodes or raise the throttle configuration if limits are too strict.
4. Investigate underlying overload (slow queries, resource pressure) that is triggering throttling.

Example fix

// before: fixed-size pool hammering the server
let pool = Pool::builder().max_size(500).build(manager);
// after: bounded pool with backoff retry
let pool = Pool::builder().max_size(50).build(manager);
// + exponential backoff on 'Server throttled'

match err {
    PsqlError::ServerThrottle(reason) => {
        warn!("throttled: {}", reason);
        backoff_and_retry();
    }
    other => return Err(other),
}

When it happens

Trigger: Connecting or issuing requests while the server is under a throttle policy (e.g. frontend connection or query admission throttling) — the string payload explains which throttle triggered.

Common situations: Too many concurrent connections from one deployment; bursty client traffic overwhelming the frontend; rate limiting during cluster overload or leader transitions.

Related errors

• ALTER SINK_RATE_LIMIT is not for sink into table
• ALTER SOURCE_RATE_LIMIT is not for table without source
• ALTER TABLE SET SOURCE RATE LIMIT is not supported for…
• failed to write unprocessed items to DynamoDB sink after…
• rate limit control channel closed

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

Appendix: source

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

    #[error(transparent)]
    Uncategorized(
        #[from]
        #[backtrace]
        BoxedError,
    ),

    #[error("Panicked when handling the request: {0}
This is a bug. We would appreciate a bug report at:
  https://github.com/risingwavelabs/risingwave/issues/new?labels=type%2Fbug&template=bug_report.yml")]
    Panic(String),

    #[error("Unable to setup an SSL connection")]
    SslError(#[from] openssl::ssl::Error),

    #[error("terminating connection due to idle-in-transaction timeout")]
    IdleInTxnTimeout,

    #[error("Server throttled: {0}")]
    ServerThrottle(String),
}

#[derive(Debug)]
pub struct ProtocolViolationError(String);

impl fmt::Display for ProtocolViolationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

impl std::error::Error for ProtocolViolationError {
    fn provide<'a>(&'a self, request: &mut std::error::Request<'a>) {
        request.provide_value(PostgresErrorCode::ProtocolViolation);
    }
}

View on GitHub (pinned to 6469eb736d)