influxdata/influxdb · error · Error

Unknown server error

Error message

Unknown server error: {0}

What it means

The `Error::Unknown` variant of the influxdb_iox_client client error enum. It wraps a `ServerError<()>` and is produced when the server returned a gRPC status code the client did not explicitly map (an unrecognized or unspecified status). It means the client cannot classify what went wrong on the server side.

Solutions

1. Inspect the wrapped ServerError payload (message, source) to see what the server actually returned.
2. Check client/server version compatibility; upgrade or downgrade the influxdb_iox_client crate to match the server.
3. Check server logs for the corresponding request to find the root cause (panic, internal error).
4. Retry the request if transient; report a bug with the full wrapped payload if the status is persistently unmapped.

Example fix

// before
let err = client.query(request).await.unwrap();
// after
match client.query(request).await {
    Ok(resp) => resp,
    Err(e) => {
        if let Error::Unknown(se) = &e {
            tracing::error!("unmapped server status: {}", se);
        }
        return Err(e);
    }
}

fn is_unknown(e: &Error) -> bool { matches!(e, Error::Unknown(_)) }

match result {
    Err(Error::Unknown(se)) => { log::error!("unmapped server error: {se}"); fallback_or_retry() }
    other => other,
}

When it happens

Trigger: A gRPC/arrow-flight or HTTP call to an InfluxDB IOx server returned a status code outside the explicitly handled set (Cancelled, InvalidArgument, DeadlineExceeded, NotFound, etc.), or an 'UNKNOWN' status was transmitted, so the `From<ServerError>` conversion falls through to `Error::Unknown`.

Common situations: Talking to an IOx server of a different version that emits newer/renamed status codes; a proxy or load balancer returning a malformed error response; genuine server panics or crashes surfaced as an opaque gRPC UNKNOWN status.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• Deadline expired before operation could complete
• {0}
• Client specified an invalid argument
• Handshake failed
• Operation was attempted past the valid range

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/d97cd2829e24d8ec. Report an issue: GitHub.

Appendix: source

Thrown at core/influxdb_iox_client/src/client/error.rs:69

    fn try_decode(status: &Status) -> Option<Self> {
        generated_types::google::decode_not_found(status).next()
    }
}

impl ServerErrorDetails for PreconditionViolation {
    fn try_decode(status: &Status) -> Option<Self> {
        generated_types::google::decode_precondition_violation(status).next()
    }
}

/// The errors returned by this client
#[derive(Error, Debug)]
#[expect(missing_docs)]
pub enum Error {
    #[error("The operation was cancelled: {0}")]
    Cancelled(ServerError<()>),

    #[error("Unknown server error: {0}")]
    Unknown(ServerError<()>),

    #[error("Client specified an invalid argument: {0}")]
    InvalidArgument(Box<ServerError<FieldViolation>>),

    #[error("Deadline expired before operation could complete: {0}")]
    DeadlineExceeded(ServerError<()>),

    #[error("{0}")]
    NotFound(Box<ServerError<NotFound>>),

    #[error("Some entity that we attempted to create already exists: {0}")]
    AlreadyExists(Box<ServerError<AlreadyExists>>),

    #[error("The caller does not have permission to execute the specified operation: {0}")]
    PermissionDenied(ServerError<()>),

    #[error("Some resource has been exhausted: {0}")]

View on GitHub (pinned to 06200ef96b)