hasura/graphql-engine · error · GraphqlConfigError

graphql configuration should be defined only once in supergr

Error message

graphql configuration should be defined only once in supergraph

What it means

Thrown by the graphql_config resolution stage when the supergraph contains more than one GraphqlConfig definition. The supergraph must have exactly one `graphql` configuration block; duplicates create ambiguity about which limit/offset/filter/orderBy field names apply. Raised during metadata resolution.

Source

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

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"
    )]
    MissingOrderByInputFieldInGraphqlConfig,
    #[error(

View on GitHub (pinned to 724551b9ae)

Solutions

1. Locate all GraphqlConfig objects in the supergraph and delete all but one
2. If merging subgraphs, designate one source of truth for the graphql config and strip it from the others before merging
3. If tooling auto-injects a default config, disable the injection when the document already declares one

Example fix

// before
{"graphql": {"limitInput": {"fieldName": "limit"}}, "subgraphs": [{"graphql": {"limitInput": {"fieldName": "l"}}}]}
// after
{"graphql": {"limitInput": {"fieldName": "limit"}}, "subgraphs": [{}]}

let count = metadata.objects.iter().filter(|o| o.type_ == "GraphqlConfig").count();
assert_eq!(count, 1, "expected exactly one GraphqlConfig, found {}", count);

fn has_single_graphql_config(md: &Metadata) -> bool {
    md.objects.iter().filter(|o| o.type_ == "GraphqlConfig").count() == 1
}

match resolve_metadata(supergraph) {
    Err(ContextualError::GraphqlConfig(GraphqlConfigError::MultipleGraphqlConfigDefinition)) => /* dedupe configs and retry */,
    other => other,
}

When it happens

Trigger: Resolving supergraph metadata that contains two or more objects of the GraphqlConfig type (e.g. two subgraphs each contributing their own `graphql` config, or a copy-paste duplication in a hand-written metadata file).

Common situations: Federating/merging multiple subgraph metadata files that each already had a graphql config; copy-pasting a config block while editing metadata; tooling that injects a default graphql config into a document that already declares one.

Related errors

• graphql configuration is not defined in supergraph
• Field mapping not found for the field {field_name:} of type
• Object type '{type_name}' not found
• Argument mapping not found for the argument {argument_name:}
• Cannot add query root field {0} as it already in use

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