hasura/graphql-engine · error · Error

Error in converting the header value corresponding to the {h

Error message

Error in converting the header value corresponding to the {header_name} to a String - {error}

What it means

In webhook-based authentication, a request header value failed to convert to a UTF-8 string (http::HeaderValue::to_str returns ToStrError for non-ASCII bytes). The header can't be forwarded to the auth webhook.

Source

Thrown at v3/crates/auth/hasura-authn-webhook/src/webhook.rs:22

use std::time::Duration;

use auth_base::{
    AuthenticateResponse, Identity, Role, RoleAuthorization, SessionVariableName,
    SessionVariableValue,
};
use axum::http::{HeaderMap, HeaderName, StatusCode};
use reqwest::{Url, header::ToStrError};
use serde::{Deserialize, Deserializer, Serialize, Serializer, de::Error as SerdeDeError};

use all_or_list::AllOrList;
use hasura_authn_core as auth_base;
use open_dds::{EnvironmentValue, session_variables};
use schemars::JsonSchema;
use tracing_util::{ErrorVisibility, SpanVisibility, TraceableError};

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error(
        "Error in converting the header value corresponding to the {header_name} to a String - {error}"
    )]
    ErrorInConvertingHeaderValueToString {
        header_name: HeaderName,
        error: ToStrError,
    },
    #[error("The Authentication hook has denied to execute the request.")]
    AuthenticationFailed { status: reqwest::StatusCode },
    #[error("Internal Error - {0}")]
    Internal(#[from] InternalError),
}

impl TraceableError for Error {
    fn visibility(&self) -> ErrorVisibility {
        // For the purpose of traces, all webhook errors should be developer facing.
        ErrorVisibility::User
    }
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Identify the offending header via {header_name} and capture/forward it as bytes (to_bytes) instead of to_str
2. Ensure clients send only ASCII/UTF-8 header values
3. Sanitize or skip non-UTF-8 headers before forwarding to the webhook

Example fix

// before
let value = header_value.to_str()?;
// after
let value = std::str::from_utf8(header_value.as_bytes()).map_err(|_| Error::ErrorInConvertingHeaderValueToString{..})?; // or use as_bytes() directly

const isAsciiHeader = (v: string) => /^[\x00-\x7F]*$/.test(v);

Catch ToStrError and fall back to forwarding header bytes (HeaderValue::as_bytes) or skip the header.

When it happens

Trigger: The outgoing webhook request forwards incoming headers; any header containing non-ASCII/invalid UTF-8 bytes triggers this when converted with to_str().

Common situations: Clients sending binary or latin-1 encoded header values; middleware injecting non-UTF-8 headers; headers with raw bytes from upstream proxies.

Related errors

• Invalid URL for auth webhook: {0}
• JWT Authorization token source: Header name {header_name} no
• Error in parsing the {header_name} header: {err}
• The Authentication hook has denied to execute the request.
• unable to fetch introspection schema: %w

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