hasura/graphql-engine · error · AggregateExpressionError

the aggregate expression {name} specifies an aggregation fun

Error message

the aggregate expression {name} specifies an aggregation function '{function_name}' that uses an unknown type for its return type: {type_name}

What it means

An aggregate expression declares an aggregation function whose `return_type` references a custom type that the metadata resolver does not know about. All return types must resolve to either built-in scalar types or custom types defined in the same metadata.

Source

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

    },

    #[error(
        "the aggregate expression {name} specifies an operand scalar type that cannot be found: {type_name}"
    )]
    AggregateOperandScalarTypeNotFound {
        name: Qualified<AggregateExpressionName>,
        type_name: Qualified<CustomTypeName>,
    },

    #[error(
        "the aggregate expression {name} has duplicate definitions of the aggregation function '{function_name}'"
    )]
    AggregateOperandFunctionDuplicated {
        name: Qualified<AggregateExpressionName>,
        function_name: AggregationFunctionName,
    },

    #[error(
        "the aggregate expression {name} specifies an aggregation function '{function_name}' that uses an unknown type for its return type: {type_name}"
    )]
    AggregateOperandFunctionUnknownReturnType {
        name: Qualified<AggregateExpressionName>,
        function_name: AggregationFunctionName,
        type_name: CustomTypeName,
    },

    #[error(
        "the aggregate expression {name} defines an aggregation function mapping to an unknown data connector: {data_connector_name}"
    )]
    AggregateOperandDataConnectorMissing {
        name: Qualified<AggregateExpressionName>,
        data_connector_name: Qualified<DataConnectorName>,
    },

    #[error(
        "the aggregate expression {name} defines an aggregation function mapping to a data connector that does not support aggregates: {data_connector_name}"

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the exact type name in the error and verify a matching type exists in your metadata (correct spelling, namespace/subgraph)
2. If the type lives elsewhere, qualify the return type with the right subgraph/namespace or move the type into scope
3. If the type was removed intentionally, switch the function's return type to a built-in scalar (e.g. Float, Int)
4. Rebuild metadata with `ddn build`

Example fix

# before
functions:
  - name: avg
    return_type: my_namespace.Revenue # undefined type
# after
functions:
  - name: avg
    return_type: Float

# Collect known custom type names from all kinds: ObjectType/scalar metadata, then:
known = {t['name'] for t in all_types}
assert fn_return_type.split('.')[-1] in known or fn_return_type in BUILTIN_SCALARS, f'unknown return type {fn_return_type}'

When it happens

Trigger: An aggregate expression function entry whose return type references a `CustomTypeName` that has no corresponding ObjectType/scalar definition in the resolved metadata (misspelled name, wrong subgraph/namespace, or type file not included).

Common situations: Renaming or deleting a custom scalar type without updating aggregate expressions; referencing a type from a different namespace; a missing `types` metadata file in the build; case/typo mistakes in type names.

Related errors

• the aggregate expression {name} has duplicate definitions of
• the aggregate expression {name} defines an aggregation funct
• the aggregate expression {name} defines an aggregation funct
• Source type {object_type_name} referenced in the definition
• the return type used on the {count_type} aggregate ({return_

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