hasura/graphql-engine · warning · Warning

AuthConfig v2 is deprecated. Please consider upgrading to Au

Error message

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

What it means

A warning emitted during auth config generation when the metadata declares AuthConfig v2. v2 is deprecated; the build still succeeds but future releases will reject it, so an upgrade to v4 is recommended.

Source

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

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

  1. Run the provided OpenDD metadata migration to upgrade the auth config to v4
  2. Manually update `version: 2` to `version: 4` and adjust any v2-only fields per the v4 schema
  3. Validate the upgraded metadata with the build; treat remaining warnings as errors to catch regressions

Example fix

// before
authConfig: { version: 2 }
// 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 v2 is deprecated") => plan_migration(e),
    r => r,
}

Prevention

When it happens

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

Common situations: Long-lived projects carrying v2 auth metadata through an engine upgrade without running the metadata migration tooling.

Related errors

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