hasura/graphql-engine · warning · Warning

AuthConfig v3 is deprecated. Please consider upgrading to Au

Error message

AuthConfig v3 is deprecated. Please consider upgrading to AuthConfig v4.

What it means

A warning emitted during auth config generation when the metadata declares AuthConfig v3. v3 still builds but is deprecated and will be removed; upgrading to v4 is recommended.

Source

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

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

View on GitHub (pinned to 724551b9ae)

Solutions

Migrate the auth config from v3 to v4 using the metadata migration tooling
Review the v3→v4 changelog for behavioral differences (e.g. role emulation removal) before upgrading
Rebuild and confirm no deprecation warnings remain

Example fix

// before
authConfig: { version: 3 }
// after
authConfig: { version: 4 }

Defensive patterns

Strategy: validation

Validate before calling

if auth_config.version != 4 {
    eprintln!("warning: AuthConfig v{} is deprecated; upgrade to v4", auth_config.version);
}

Type guard

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

Try / catch

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

Prevention

Migrate v3 configs before the next engine upgrade
Verify migrated config behavior in staging
Enable warnings-as-errors in CI to force timely migration

When it happens

Trigger: Auth config generation encounters an AuthConfig with version: 3 in the OpenDD metadata.

Common situations: Recently upgraded projects whose auth metadata was authored for the previous major release (v3) and has not yet been migrated.

Related errors

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