hasura/graphql-engine · error · BuildRequestError

Invalid header value for header {header_name}: {error}

Error message

Invalid header value for header {header_name}: {error}

What it means

A header value forwarded to the pre-NDC-response plugin failed conversion to http::HeaderValue. Values must be visible ASCII; the error names the header and includes the underlying InvalidHeaderValue cause. Typically caused by non-ASCII session data being injected into a forwarded header.

Source

Thrown at v3/crates/plugins/pre-ndc-response-plugin/src/execute.rs:46

        plugin_name: String,
        error: serde_json::Value,
    },
    #[error("User error from plugin {plugin_name}")]
    PluginUserError {
        plugin_name: String,
        error: serde_json::Value,
    },
}

#[derive(Debug, thiserror::Error)]
pub enum BuildRequestError {
    #[error("Invalid header name {header_name}: {error}")]
    InvalidHeaderName {
        header_name: String,
        #[source]
        error: InvalidHeaderName,
    },
    #[error("Invalid header value for header {header_name}: {error}")]
    InvalidHeaderValue {
        header_name: HeaderName,
        #[source]
        error: InvalidHeaderValue,
    },
    #[error("Failed to convert session: {0}")]
    SessionConversionError(String),
    #[error("Failed to convert session variable '{variable_name}': {error}")]
    SessionVariableConversionError {
        variable_name: SessionVariableName,
        error: serde_json::Error,
    },
    #[error("Serialization error: {0}")]
    SerializationError(#[from] serde_json::Error),
}

impl TraceableError for Error {
    fn visibility(&self) -> ErrorVisibility {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Encode the value (percent-encoding or base64) before forwarding
2. Forward only ASCII-safe identifiers in headers
3. Strip/trim values sourced from env vars
4. Add a test asserting all forwarded session variables are ASCII

Example fix

// before
HeaderValue::from_str(user_display_name)?;
// after
HeaderValue::from_str(&urlencode(user_display_name))?;

fn ascii_header_value(v: &str) -> bool {
    v.bytes().all(|b| (32..=127).contains(&b) || b == b'\t')
}

When it happens

Trigger: Forwarding a session variable (user name, raw token bytes) into a header where the value contains non-ASCII or control characters, so HeaderValue::from_str fails in build_request.

Common situations: Usernames/display names with unicode; JWT claims containing binary data; values with trailing newlines from env vars.

Related errors

• Invalid header value for header {header_name}: {error}
• Invalid header name {header_name}: {error}
• Invalid header name {header_name}: {error}
• Error while building the request for the pre-response plugin
• Invalid header name: {0}

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