hasura/graphql-engine · warning · Warning

Header value '{0}' is not a valid header value for header '{

Error message

Header value '{0}' is not a valid header value for header '{1}' in the auth config

What it means

A warning raised during auth config generation: the configured value for a named header is not a valid HTTP header value (control characters, invalid formatting). It can be promoted to an error via OpenDD flags.

Source

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

        .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 {
    #[error("Invalid URL for auth webhook: {0}")]
    InvalidAuthWebhookUrl(String),

View on GitHub (pinned to 724551b9ae)

Solutions

Sanitize the header value — strip newlines, control characters, and invalid escapes
Use static, well-formed values for headers in the auth config
Run config validation with strict flags enabled so bad header values are caught at build time, not runtime

Example fix

// before
headerValues: { "X-Hasura-Secret": "abc\ndef" }
// after
headerValues: { "X-Hasura-Secret": "abcdef" }

Defensive patterns

Strategy: validation

Validate before calling

use http::HeaderValue;
for (name, value) in auth_config.header_values() {
    HeaderValue::from_str(value)
        .map_err(|_| format!("invalid header value for {name}"))?;
}

Type guard

fn isValidHeaderValue(v: &str) -> bool {
    !v.is_empty() && v.bytes().all(|b| b == b'\t' || (0x20..=0x7e).contains(&b) || b == b'\x80') == false
}

Prevention

Strip newlines/control characters from templated header values
Use plain ASCII literals where possible
Validate the full auth config with strict flags before deploy

When it happens

Trigger: An auth config entry sets a header value containing characters that fail HTTP header-value validation (newlines, control bytes, malformed quoted strings).

Common situations: Injecting environment-expanded or templated strings with newlines/escape sequences into header values, or copying values from browser devtools with trailing whitespace/control characters.

Related errors

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