hasura/graphql-engine · warning · Warning

Header '{0}', used in the auth config, is not a valid header

Error message

Header '{0}', used in the auth config, is not a valid header name

What it means

A warning raised during auth config generation: a header name referenced in the auth configuration (e.g. for session-variable extraction from headers) is not a syntactically valid HTTP header name. Depending on flags this warning can be promoted to a hard error.

Source

Thrown at v3/crates/auth/hasura-authn/src/lib.rs:270

            jsonpath::JSONPath::new(),
        )
        .unwrap()
    }
}

/// Warnings for the user raised during auth config generation
/// These are things that don't break the build, but may do so in future
#[derive(Debug, PartialEq, thiserror::Error)]
pub enum Warning {
    #[error(
        "AuthConfig v1 is deprecated. `allowRoleEmulationBy` has been removed. Please consider upgrading to AuthConfig v4."
    )]
    PleaseUpgradeV1ToV4,
    #[error("AuthConfig v2 is deprecated. Please consider upgrading to AuthConfig v4.")]
    PleaseUpgradeV2ToV4,
    #[error("AuthConfig v3 is deprecated. Please consider upgrading to AuthConfig v4.")]
    PleaseUpgradeV3ToV4,
    #[error("Header '{0}', used in the auth config, is not a valid header name")]
    InvalidHeaderName(String),
    #[error("Header value '{0}' is not a valid header value for header '{1}' in the auth config")]
    InvalidHeaderValue(String, String),
}

impl Warning {
    pub fn should_be_an_error(&self, flags: &open_dds::flags::OpenDdFlags) -> bool {
        match self {
            Warning::InvalidHeaderName(_) | Warning::InvalidHeaderValue(_, _) => {
                flags.contains(open_dds::flags::Flag::DisallowInvalidHeadersInAuthConfig)
            }
            _ => false,
        }
    }
}

#[derive(Debug, thiserror::Error, PartialEq)]
pub enum Error {

View on GitHub (pinned to 724551b9ae)

Solutions

Correct the header name to a valid HTTP token (alphanumerics and -_~ etc., no spaces/non-ASCII)
Check the `should_be_an_error` flag mapping — with strict flags this fails the build outright
If the header isn't needed, remove the mapping from the auth config

Example fix

// before
sessionVariables: { - header: "X Hasura-Role " }
// after
sessionVariables: { - header: "X-Hasura-Role" }

Defensive patterns

Strategy: validation

Validate before calling

use http::HeaderName;
for name in auth_config.header_names() {
    HeaderName::from_bytes(name.as_bytes())
        .map_err(|_| format!("invalid header name: {name}"))?;
}

Type guard

fn isValidHeaderName(s: &str) -> bool {
    !s.is_empty() && s.bytes().all(|b| b.is_ascii_alphanumeric() || b"-_!#$%&'*+.^`|~".contains(&b))
}

Prevention

Lint header names in the auth config with a standard parser
Avoid templating that can inject spaces into header names
Enable strict flags so bad header names fail builds early

When it happens

Trigger: An auth config entry maps a session variable to a header whose name contains invalid characters or is otherwise rejected by header-name parsing (e.g. spaces, non-ASCII, empty string).

Common situations: Typos in header names, copying curl-style header names with unusual characters, or templating bugs that inject whitespace into header names in the auth config.

Related errors

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