{"record":{"id":"587671d2b3c01181","repo":"influxdata/influxdb","slug":"handshake-failed-0","errorCode":null,"errorMessage":"Handshake failed: {0}","messagePattern":"Handshake failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"core/influxdb_iox_client/src/client/flight/mod.rs","lineNumber":60,"sourceCode":"    #[error(transparent)]\n    ArrowError(#[from] arrow::error::ArrowError),\n\n    /// An error involving an Arrow Flight operation occurred.\n    #[error(transparent)]\n    ArrowFlightError(#[from] FlightError),\n\n    /// The data contained invalid Flatbuffers.\n    #[error(\"Invalid Flatbuffer: `{0}`\")]\n    InvalidFlatbuffer(String),\n\n    /// The message header said it was a dictionary batch, but interpreting the\n    /// message as a dictionary batch returned `None`. Indicates malformed\n    /// Flight data from the server.\n    #[error(\"Message with header of type dictionary batch could not return a dictionary batch\")]\n    CouldNotGetDictionaryBatch,\n\n    /// Arrow Flight handshake failed.\n    #[error(\"Handshake failed: {0}\")]\n    HandshakeFailed(String),\n\n    /// Serializing the protobuf structs into bytes failed.\n    #[error(transparent)]\n    Serialization(#[from] prost::EncodeError),\n\n    /// Deserializing the protobuf structs from bytes failed.\n    #[error(transparent)]\n    Deserialization(#[from] prost::DecodeError),\n\n    /// Unknown IPC message type.\n    #[error(\"Unknown IPC message type: {0:?}\")]\n    UnknownMessageType(ipc::MessageHeader),\n\n    /// Unexpected schema change.\n    #[error(\"Unexpected schema change\")]\n    UnexpectedSchemaChange,\n}","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/core/influxdb_iox_client/src/client/flight/mod.rs#L42-L78","documentation":"Error variant `HandshakeFailed(String)` of the influxdb_iox_client Flight client's Error enum, thrown when the Arrow Flight handshake with the IOx server fails. The handshake is the first gRPC/tonic call made when connecting, so this wraps any transport, protocol, or authentication failure reported during `handshake()`. The inner String carries the underlying tonic/Flight error message.","triggerScenarios":"Calling the Flight client's connect/query path when the server's `handshake()` future resolves to an error: server unreachable or restarted mid-handshake, TLS/transport error, server rejecting credentials during handshake, or an incompatible Flight protocol version.","commonSituations":"IOx server down or listening on a different port than configured; TLS certificate mismatch; expired or invalid bearer token rejected at handshake; version skew between client and server Arrow Flight implementations.","solutions":["Check that the IOx server is running and the configured address/port is correct","Verify TLS configuration (certificates, CA bundle) matches between client and server","Validate credentials/bearer token are present and not expired","Retry with backoff — transient network blips during startup commonly fail the handshake","Inspect the embedded message for the underlying tonic status and match it to server-side logs"],"exampleFix":"// before\nlet client = FlightClient::new(channel).await?;\n// after\nlet client = match FlightClient::new(channel).await {\n    Ok(c) => c,\n    Err(e) => {\n        if let Some(status) = e.tonic_status() {\n            eprintln!(\"handshake rejected: {}\", status);\n        }\n        return Err(e);\n    }\n};","handlingStrategy":"try-catch","validationCode":"// pre-flight: verify the server accepts gRPC connections\n// e.g. `nc -zv host 443` or a lightweight health/rpc call before creating the client","typeGuard":"fn is_handshake_failed(e: &Error) -> bool {\n    matches!(e, Error::HandshakeFailed(_))\n}","tryCatchPattern":"match client.connect().await {\n    Err(Error::HandshakeFailed(msg)) => {\n        eprintln!(\"handshake failed: {msg}; check server addr/TLS/token\");\n        // retry with backoff or surface config error\n    }\n    Err(e) => return Err(e),\n    Ok(c) => c,\n}","preventionTips":["Add a startup health check against the Flight endpoint before queries","Keep bearer tokens fresh and loaded from a validated source","Match arrow-flight/tonic versions between client and server","Use exponential backoff for transient handshake failures"],"tags":["grpc","arrow-flight","handshake","network"],"backgroundTag":"http-request-failed","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}