hasura/graphql-engine · error · BuildRequestError

Invalid header name {header_name}: {error}

Error message

Invalid header name {header_name}: {error}

What it means

While building the HTTP request to the pre-NDC-response plugin, a configured header name failed conversion to http::HeaderName. The offending name and underlying error are shown. Header names must be ASCII token characters — spaces, control bytes, and non-ASCII characters are invalid.

Source

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

    #[error("Unexpected status code: {0}")]
    UnexpectedStatusCode(u16),
    #[error("Error parsing the request: {0}")]
    PluginRequestParseError(serde_json::error::Error),
    #[error("Internal error from plugin {plugin_name}")]
    PluginInternalError {
        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,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Correct the header name in the plugin config to a valid token (letters, digits, '-')
2. Remove invisible characters/whitespace from the config value
3. Audit env-var interpolation used to build header names
4. Add config validation in CI to catch malformed header names early

Example fix

# before
forward_headers: ["x_user_id"]
# after
forward_headers: ["x-user-id"]

fn valid_header_name(s: &str) -> bool {
    !s.is_empty() && s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-')
}

When it happens

Trigger: Plugin webhook config lists forwarded headers and one name is malformed (spaces, newlines, non-ASCII), causing BuildRequestError::InvalidHeaderName during request construction.

Common situations: Hand-edited YAML config with typos; header names built from env vars that resolve to empty/garbled strings; copy-paste introducing smart quotes.

Related errors

• Invalid header name {header_name}: {error}
• Invalid header value for header {header_name}: {error}
• Invalid header value for header {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/692ce1e97cb30935. Report an issue: GitHub.