hasura/graphql-engine · warning · Warning

AuthConfig v1 is deprecated. `allowRoleEmulationBy` has been

Error message

AuthConfig v1 is deprecated. `allowRoleEmulationBy` has been removed. Please consider upgrading to AuthConfig v4.

What it means

A warning (not a hard failure unless warnings-as-errors is enabled) emitted during auth config generation: the metadata still uses AuthConfig v1, whose `allowRoleEmulationBy` capability has been removed. The build proceeds but v1 is deprecated and will break in a future release.

Source

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

                    "mode": {
                      "webhook": {
                        "url": "http://auth_hook:3060/validate-request",
                        "method": "Post"
                      }
                    }
                }
            ),
            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)

View on GitHub (pinned to 724551b9ae)

Solutions

Migrate the auth config to v4 (drop `allowRoleEmulationBy`, which no longer exists)
If you relied on role emulation, redesign it using the v4 role/session-variable model
Re-run the build and confirm the warning disappears; enable warnings-as-errors to enforce it

Example fix

// before
authConfig: { version: 1, allowRoleEmulationBy: ["admin"] }
// after
authConfig: { version: 4 }

Defensive patterns

Strategy: validation

Validate before calling

if auth_config.version == 1 {
    return Err("AuthConfig v1 is deprecated; migrate to v4 (allowRoleEmulationBy removed)");
}

Type guard

fn isSupportedAuthConfig(v: u32) -> bool { v == 4 }

Try / catch

match build_auth_config(&metadata) {
    Err(e) if e.to_string().contains("AuthConfig v1 is deprecated") => plan_migration(e),
    r => r,
}

Prevention

Run metadata migration tooling before upgrading the engine
Pin CI to reject auth config versions < 4
Track deprecation notices in release notes for each upgrade

When it happens

Trigger: Auth config generation encounters an AuthConfig of version 1 in the OpenDD metadata while building hasura-authn configuration.

Common situations: Upgrading the platform/engine to a version that no longer supports AuthConfig v1, or importing older metadata exports that still pin version 1.

Related errors

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