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-request plugin, the engine tried to convert a configured header name into an http::HeaderName and failed. The {header_name} field shows the offending string and {error} the underlying InvalidHeaderName error. Header names must be ASCII tokens — no spaces, control chars, or non-ASCII characters.

Source

Thrown at v3/crates/plugins/pre-ndc-request-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. Find the header name in the plugin's config (forwarded headers section) and correct it to a valid token like X-Request-Id
2. Trim whitespace and remove any non-ASCII/control characters from the config value
3. Check for env-var interpolation that produced an unexpected value
4. Validate header names at config load time if you maintain the config tooling

Example fix

# before
forward_headers:
  - "X User Id"   # invalid: spaces
# 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'-')
        && s.starts_with(|c: char| c.is_ascii_alphabetic())
}

When it happens

Trigger: Configuring forward_headers / header passthrough in the plugin config with an invalid name such as "X My Header", "X-Header\n", or a non-ASCII string; BuildRequestError::InvalidHeaderName is then hit when constructing the reqwest request.

Common situations: Typos or trailing whitespace in YAML/JSON connector plugin config; copy-pasting header names with smart quotes or invisible characters; env-var interpolation producing an empty or malformed name.

Related errors

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