hasura/graphql-engine · error · AggregateExpressionError

the return type used on the {count_type} aggregate ({return_

Error message

the return type used on the {count_type} aggregate ({return_type}) is unknown

What it means

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.

Source

Thrown at v3/crates/metadata-resolve/src/stages/aggregates/types.rs:284

        reason: String,
    },

    #[error(
        "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}"
    )]
    NestedObjectAggregatesNotSupportedByDataConnector {
        name: Qualified<AggregateExpressionName>,
        data_connector_name: Qualified<DataConnectorName>,
        field_name: FieldName,
    },

    #[error("graphql config error in {aggregate_expression_name}: {graphql_config_error}")]
    GraphqlConfigError {
        aggregate_expression_name: Qualified<AggregateExpressionName>,
        graphql_config_error: graphql_config::GraphqlConfigError,
    },

    #[error("the return type used on the {count_type} aggregate ({return_type}) is unknown")]
    UnknownCountReturnType {
        aggregate_expression_name: Qualified<AggregateExpressionName>,
        count_type: CountAggregateType,
        return_type: QualifiedTypeName,
    },

    #[error(
        "the return type used on the {count_type} aggregate ({return_type}) must be an integer type"
    )]
    InvalidCountReturnType {
        aggregate_expression_name: Qualified<AggregateExpressionName>,
        count_type: CountAggregateType,
        return_type: QualifiedTypeName,
    },
}

impl ContextualError for AggregateExpressionError {
    fn create_error_context(&self) -> Option<error_context::Context> {

View on GitHub (pinned to 724551b9ae)

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.

Example fix

// before
- name: total_users
  count:
    return_type: { name: Bigint, arguments: [] }  // typo / undeclared scalar
// after
- name: total_users
  count:
    return_type: { name: BigInt, arguments: [] }  // matches declared scalar

Defensive patterns

Strategy: validation

Validate before calling

// Before applying metadata, verify the return type exists
fn return_type_exists(types: &TypeGraph, rt: &QualifiedTypeName) -> bool {
    types.resolve(rt).is_some()
}
assert!(return_type_exists(&types, &aggregate.return_type));

Try / catch

Catch MetadataError at apply time and inspect the stage error; surface the aggregate expression name from the error chain to the user.

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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