{"record":{"id":"22e21ab80b3bd42d","repo":"hasura/graphql-engine","slug":"the-return-type-used-on-the-count-type-aggregate","errorCode":null,"errorMessage":"the return type used on the {count_type} aggregate ({return_type}) is unknown","messagePattern":"the return type used on the (.+?) aggregate \\((.+?)\\) is unknown","errorType":"validation","errorClass":"AggregateExpressionError","httpStatus":null,"severity":"error","filePath":"v3/crates/metadata-resolve/src/stages/aggregates/types.rs","lineNumber":284,"sourceCode":"        reason: String,\n    },\n\n    #[error(\n        \"the data connector {data_connector_name} does not support aggregates over nested object fields, such as the field {field_name} used in aggregate expression {name}\"\n    )]\n    NestedObjectAggregatesNotSupportedByDataConnector {\n        name: Qualified<AggregateExpressionName>,\n        data_connector_name: Qualified<DataConnectorName>,\n        field_name: FieldName,\n    },\n\n    #[error(\"graphql config error in {aggregate_expression_name}: {graphql_config_error}\")]\n    GraphqlConfigError {\n        aggregate_expression_name: Qualified<AggregateExpressionName>,\n        graphql_config_error: graphql_config::GraphqlConfigError,\n    },\n\n    #[error(\"the return type used on the {count_type} aggregate ({return_type}) is unknown\")]\n    UnknownCountReturnType {\n        aggregate_expression_name: Qualified<AggregateExpressionName>,\n        count_type: CountAggregateType,\n        return_type: QualifiedTypeName,\n    },\n\n    #[error(\n        \"the return type used on the {count_type} aggregate ({return_type}) must be an integer type\"\n    )]\n    InvalidCountReturnType {\n        aggregate_expression_name: Qualified<AggregateExpressionName>,\n        count_type: CountAggregateType,\n        return_type: QualifiedTypeName,\n    },\n}\n\nimpl ContextualError for AggregateExpressionError {\n    fn create_error_context(&self) -> Option<error_context::Context> {","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/metadata-resolve/src/stages/aggregates/types.rs#L266-L302","documentation":"This error is thrown while resolving the GraphQL metadata of an aggregate expression during metadata validation. A 'count' aggregate (e.g. count or distinct_count) was configured with an explicit return type in metadata, but that type name is not resolvable in the type graph — it does not correspond to any known scalar or output type. The metadata resolver refuses to proceed because it cannot generate a GraphQL field whose return type is unknown.","triggerScenarios":"Defining an aggregate expression with count_type: count (or distinct_count) and a return type whose QualifiedTypeName does not match any type declared in the metadata (misspelled scalar, missing scalar definition, wrong qualification/namespace of the type name).","commonSituations":"Typos in the return type name of a count aggregate in the metadata YAML/JSON; referencing a scalar that was deleted or renamed between metadata versions; forgetting to define a custom scalar before using it as the aggregate return type; namespace/qualification mismatches after moving types between subgraphs.","solutions":["Check the aggregate expression's return type in your metadata and fix any typo in the type name (must exactly match a declared scalar/output type name including its namespace).","If using a custom scalar, ensure the scalar type is actually declared in the metadata's types section.","If the type was recently renamed or moved, update the aggregate's return_type reference to the new qualified name.","Re-apply/validate the metadata to confirm the error disappears."],"exampleFix":"// before\n- name: total_users\n  count:\n    return_type: { name: Bigint, arguments: [] }  // typo / undeclared scalar\n// after\n- name: total_users\n  count:\n    return_type: { name: BigInt, arguments: [] }  // matches declared scalar","handlingStrategy":"validation","validationCode":"// Before applying metadata, verify the return type exists\nfn return_type_exists(types: &TypeGraph, rt: &QualifiedTypeName) -> bool {\n    types.resolve(rt).is_some()\n}\nassert!(return_type_exists(&types, &aggregate.return_type));","typeGuard":null,"tryCatchPattern":"Catch MetadataError at apply time and inspect the stage error; surface the aggregate expression name from the error chain to the user.","preventionTips":["Define all custom scalars before referencing them in aggregate return types.","Lint metadata in CI for references to undeclared type names.","Use exact qualified type names when configuring aggregates."],"tags":["hasura","metadata","aggregates","graphql","type-resolution"],"backgroundTag":"schema-validation-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}