hasura/graphql-engine · error · ConnectionInitError

Invalid header value: {0}

Error message

Invalid header value: {0}

What it means

This error is thrown when a `connection_init` payload carries a header value that fails HTTP header value validation (via `http::header::InvalidHeaderValue`). The graphql-ws protocol layer converts connection-init payload fields into HTTP headers for authentication, and any value containing invalid characters (e.g. control bytes) produces this error.

Source

Thrown at v3/crates/graphql/graphql-ws/src/protocol/init.rs:124

                        }
                        ConnectionInitState::Initialized { .. } => {
                            Err(ConnectionInitError::AlreadyInitialized)
                        }
                    }
                })
            },
        )
        .await
}

/// Error types that may occur during connection initialization.
#[derive(Debug, thiserror::Error)]
pub enum ConnectionInitError {
    #[error("Connection already initialized")]
    AlreadyInitialized,
    #[error("Invalid header name: {0}")]
    InvalidHeaderName(#[from] http::header::InvalidHeaderName),
    #[error("Invalid header value: {0}")]
    InvalidHeaderValue(#[from] http::header::InvalidHeaderValue),
    #[error("AuthError: {0}")]
    Authn(#[from] AuthError),
    #[error("SessionError: {0}")]
    Session(#[from] SessionError),
}

impl tracing_util::TraceableError for ConnectionInitError {
    fn visibility(&self) -> tracing_util::ErrorVisibility {
        tracing_util::ErrorVisibility::User
    }
}

/// Parses headers from a given map of strings into an `http::HeaderMap`.
/// Returns a parsed header map or an error if the headers are invalid.
fn parse_headers(map: HashMap<String, String>) -> Result<http::HeaderMap, ConnectionInitError> {
    let mut headers = http::HeaderMap::new();
    for (key, value) in map {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the connection_init payload parameters and locate the header value with illegal characters
2. Sanitize or re-encode the offending value (strip newlines/control bytes) before connecting
3. If the token is binary, base64-encode it instead of passing raw bytes
4. Wrap connection setup to log the offending header name/value for faster diagnosis

Example fix

// before
ws.send(JSON.stringify({type:'connection_init',payload:{headers:{Authorization:`Bearer ${rawToken}`}}}));
// after
const safe = rawToken.replace(/[\r\n\x00-\x1f]/g,'');
ws.send(JSON.stringify({type:'connection_init',payload:{headers:{Authorization:`Bearer ${safe}`}}}));

function isValidHeaderValue(v){ return typeof v==='string' && !/[\x00-\x1f\x7f]/.test(v); }

catch (e) { if (String(e).includes('Invalid header value')) { /* sanitize payload and retry connect */ } }

When it happens

Trigger: Sending a `connection_init` WebSocket message whose payload parameters include a header string with characters illegal in an HTTP header value (e.g. a bearer token containing a newline, or binary/control characters). It is surfaced through `ConnectionInitError::InvalidHeaderValue` during connection initialization.

Common situations: Malformed or corrupt auth tokens pasted into the connection init payload; proxied clients that inject invalid characters into header-like parameters; tests with raw string tokens containing control characters.

Related errors

• AuthError: {0}
• {SEC_WEBSOCKET_PROTOCOL} header: {0}
• Connection already initialized
• Invalid header name: {0}
• SessionError: {0}

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/77051878ae90d470. Report an issue: GitHub.