{"record":{"id":"9d9c6f62b5eb314f","repo":"hasura/graphql-engine","slug":"graphql-configuration-is-not-defined-in-supergraph","errorCode":null,"errorMessage":"graphql configuration is not defined in supergraph","messagePattern":"graphql configuration is not defined in supergraph","errorType":"validation","errorClass":"GraphqlConfigError","httpStatus":null,"severity":"error","filePath":"v3/crates/metadata-resolve/src/stages/graphql_config/error.rs","lineNumber":7,"sourceCode":"use graphql_types as ast;\n\nuse crate::types::error::ContextualError;\n\n#[derive(Debug, thiserror::Error)]\npub enum GraphqlConfigError {\n    #[error(\"graphql configuration is not defined in supergraph\")]\n    MissingGraphqlConfig,\n    #[error(\"graphql configuration should be defined only once in supergraph\")]\n    MultipleGraphqlConfigDefinition,\n    #[error(\n        \"the fieldName for limitInput needs to be defined in GraphqlConfig, when models have a selectMany graphql API\"\n    )]\n    MissingLimitFieldInGraphqlConfig,\n    #[error(\n        \"the fieldName for offsetInput needs to be defined in GraphqlConfig, when models have a selectMany graphql API\"\n    )]\n    MissingOffsetFieldInGraphqlConfig,\n    #[error(\n        \"the filterInput needs to be defined in GraphqlConfig, when models have filterExpressionType\"\n    )]\n    MissingFilterInputFieldInGraphqlConfig,\n    #[error(\n        \"the orderByInput needs to be defined in GraphqlConfig, when models have orderByExpressionType\"\n    )]","sourceCodeStart":1,"sourceCodeEnd":25,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/metadata-resolve/src/stages/graphql_config/error.rs#L1-L25","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a top-level GraphqlConfig object to your supergraph metadata (e.g. {\"graphql\": {\"limitInput\": {...}, \"offsetInput\": {...}}})","If generating metadata programmatically, ensure the graphql config emitter runs before the resolve stage","Check for typos in the key name — it must be exactly `graphql`"],"exampleFix":"// before\n{\"models\": [{\"name\": \"users\", \"graphqlApi\": {\"selectMany\": {}}}]}\n// after\n{\"graphql\": {\"limitInput\": {\"fieldName\": \"limit\"}, \"offsetInput\": {\"fieldName\": \"offset\"}}, \"models\": [{\"name\": \"users\", \"graphqlApi\": {\"selectMany\": {}}}]}","handlingStrategy":"validation","validationCode":"// Before resolving, check the supergraph has exactly one graphql config\nlet graphqlConfigs = metadata.objects.iter().filter(|o| o.type_ == \"GraphqlConfig\");\nassert!(graphql_configs.clone().count() >= 1, \"missing graphql config in supergraph\");","typeGuard":"fn has_graphql_config(md: &Metadata) -> bool {\n    md.objects.iter().any(|o| o.type_ == \"GraphqlConfig\")\n}","tryCatchPattern":"match resolve_metadata(supergraph) {\n    Err(ContextualError::GraphqlConfig(GraphqlConfigError::MissingGraphqlConfig)) => /* prompt user to add config */,\n    other => other,\n}","preventionTips":["Include a GraphqlConfig in every metadata template from the start","Run metadata validation in CI before deploy","When generating metadata, assert the graphql block is emitted"],"tags":["graphql","metadata","supergraph","validation","config"],"backgroundTag":"missing-graphql-config","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}