hasura/graphql-engine · error · GraphqlConfigError

graphql configuration is not defined in supergraph

Error message

graphql configuration is not defined in supergraph

What it means

This error is thrown by the metadata-resolve stage that validates a supergraph metadata document. It signals that no `graphql` configuration block (GraphqlConfig) was found anywhere in the supergraph, even though the resolver needs one to build GraphQL APIs for models. It is a metadata validation error raised during resolution, before any engine starts.

Source

Thrown at v3/crates/metadata-resolve/src/stages/graphql_config/error.rs:7

use graphql_types as ast;

use crate::types::error::ContextualError;

#[derive(Debug, thiserror::Error)]
pub enum GraphqlConfigError {
    #[error("graphql configuration is not defined in supergraph")]
    MissingGraphqlConfig,
    #[error("graphql configuration should be defined only once in supergraph")]
    MultipleGraphqlConfigDefinition,
    #[error(
        "the fieldName for limitInput needs to be defined in GraphqlConfig, when models have a selectMany graphql API"
    )]
    MissingLimitFieldInGraphqlConfig,
    #[error(
        "the fieldName for offsetInput needs to be defined in GraphqlConfig, when models have a selectMany graphql API"
    )]
    MissingOffsetFieldInGraphqlConfig,
    #[error(
        "the filterInput needs to be defined in GraphqlConfig, when models have filterExpressionType"
    )]
    MissingFilterInputFieldInGraphqlConfig,
    #[error(
        "the orderByInput needs to be defined in GraphqlConfig, when models have orderByExpressionType"
    )]

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add a top-level GraphqlConfig object to your supergraph metadata (e.g. {"graphql": {"limitInput": {...}, "offsetInput": {...}}})
2. If generating metadata programmatically, ensure the graphql config emitter runs before the resolve stage
3. Check for typos in the key name — it must be exactly `graphql`

Example fix

// before
{"models": [{"name": "users", "graphqlApi": {"selectMany": {}}}]}
// after
{"graphql": {"limitInput": {"fieldName": "limit"}, "offsetInput": {"fieldName": "offset"}}, "models": [{"name": "users", "graphqlApi": {"selectMany": {}}}]}

// Before resolving, check the supergraph has exactly one graphql config
let graphqlConfigs = metadata.objects.iter().filter(|o| o.type_ == "GraphqlConfig");
assert!(graphql_configs.clone().count() >= 1, "missing graphql config in supergraph");

fn has_graphql_config(md: &Metadata) -> bool {
    md.objects.iter().any(|o| o.type_ == "GraphqlConfig")
}

match resolve_metadata(supergraph) {
    Err(ContextualError::GraphqlConfig(GraphqlConfigError::MissingGraphqlConfig)) => /* prompt user to add config */,
    other => other,
}

When it happens

Trigger: Resolving/validating supergraph metadata where at least one model exposes a GraphQL API (selectOne/selectMany/selectAggregate, filterExpressionType, or orderByExpressionType) but the top-level `graphql` configuration object is absent from the metadata.

Common situations: Hand-writing or generating Hasura-style metadata and forgetting the GraphqlConfig block; upgrading to a version that made the graphql config mandatory; merging subgraph metadata files and dropping the config section.

Related errors

• graphql configuration should be defined only once in supergr
• the filterInput needs to be defined in GraphqlConfig, when m
• the orderByInput needs to be defined in GraphqlConfig, when
• the orderByInput.enumTypeNames needs to be defined in Graphq
• invalid directions: {directions} defined in orderByInput of

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