hasura/graphql-engine · error · Error

The Authentication hook has denied to execute the request.

Error message

The Authentication hook has denied to execute the request.

What it means

The authentication webhook returned a non-success status, i.e. the auth hook explicitly denied the request. Execution stops before reaching the data layer.

Source

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

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
    }
}

#[derive(Debug, thiserror::Error)]
pub enum InternalError {
    #[error("Error while making the authentication HTTP request to the webhook - {0}")]
    ErrorWhileMakingHTTPRequestToTheAuthHook(reqwest::Error),
    #[error(
        "The authentication hook has returned the status {0}. Only 200 and 401 response status are recognized."

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the webhook's decision logic and its logs for why it returned a denial status
2. Verify the request contains the headers the webhook expects
3. If the webhook itself errored (5xx from your handler), fix the handler bug
4. Confirm webhook URL and forwarding config in metadata

Example fix

// before: webhook returns 401 for all requests due to a bug
// after: webhook validates Authorization header and returns 200 with roles, 401 only when truly unauthenticated

// Pre-check webhook health
const ok = await fetch(webhookUrl, { method: 'HEAD' });

On denial, return 401 to the client with a generic message; log the webhook's status/body internally for diagnosis.

When it happens

Trigger: Your auth webhook endpoint returns 4xx (e.g. 401/403) for the forwarded request headers, so the engine refuses to execute the GraphQL request.

Common situations: Webhook rejects expired/invalid session tokens; webhook misconfigured to reject unknown headers; webhook endpoint down returning errors; test requests missing required auth headers.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Session variable not found: {name}
• Serde error: {error}
• Condition {condition_hash} not found
• Expected array or null for right-hand value of contains oper
• Expected number for {side}-hand value of comparison operatio

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