influxdata/influxdb · error · Error

Unknown IPC message type

Error message

Unknown IPC message type: {0:?}

What it means

Error variant `UnknownMessageType(ipc::MessageHeader)` thrown while decoding the Arrow Flight IPC stream: the client received an IPC message whose header type it does not know how to handle. Indicates the server sent data outside the set of message types the client understands, i.e. malformed or unsupported Flight data.

Solutions

1. Upgrade the influxdb_iox_client / arrow dependencies so client IPC support matches the server version
2. Check server logs for what message type it emitted and whether it is intentional
3. Rule out intermediaries (proxies) altering the gRPC stream
4. Capture the Debug value in the error to identify the exact unsupported header type
5. Pin matching versions of arrow-flight and datafusion on both sides

Example fix

// before
let batch = client.query(sql).await?;
// after
let batch = client.query(sql).await.map_err(|e| {
    if matches!(e, Error::UnknownMessageType(_)) {
        eprintln!("server sent unsupported IPC frame; check client/server arrow version parity");
    }
    e
})?;

// check version parity of arrow-flight/arrow-ipc client vs server before decoding

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

match stream.next().await {
    Err(Error::UnknownMessageType(hdr)) => {
        eprintln!("unsupported IPC frame {hdr:?}; upgrade client libs");
    }
    other => { /* normal handling */ }
}

When it happens

Trigger: Reading a Flight data stream (`select`/query results) when the server emits an IPC `MessageHeader` variant not handled by the client's match (e.g. dictionary, tensor, or a newer IPC message type added on the server but not supported by this client version).

Common situations: Client and Arrow/Flight library version mismatch where the server encodes newer IPC message types; a corrupt or truncated IPC stream from a failing server; proxy/middleware rewriting Flight frames.

Related errors

• deserializing show tables
• Handshake failed
• Unexpected schema change

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

Appendix: source

Thrown at core/influxdb_iox_client/src/client/flight/mod.rs:72

    /// message as a dictionary batch returned `None`. Indicates malformed
    /// Flight data from the server.
    #[error("Message with header of type dictionary batch could not return a dictionary batch")]
    CouldNotGetDictionaryBatch,

    /// Arrow Flight handshake failed.
    #[error("Handshake failed: {0}")]
    HandshakeFailed(String),

    /// Serializing the protobuf structs into bytes failed.
    #[error(transparent)]
    Serialization(#[from] prost::EncodeError),

    /// Deserializing the protobuf structs from bytes failed.
    #[error(transparent)]
    Deserialization(#[from] prost::DecodeError),

    /// Unknown IPC message type.
    #[error("Unknown IPC message type: {0:?}")]
    UnknownMessageType(ipc::MessageHeader),

    /// Unexpected schema change.
    #[error("Unexpected schema change")]
    UnexpectedSchemaChange,
}

impl Error {
    /// Extracts the underlying tonic status, if any
    pub fn tonic_status(&self) -> Option<&Status> {
        if let Self::ArrowFlightError(FlightError::Tonic(status)) = self {
            Some(status)
        } else {
            None
        }
    }
}

View on GitHub (pinned to 06200ef96b)