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}) must be an integer type

What it means

During metadata resolution of aggregate expressions, the return type explicitly configured for a count aggregate was resolved successfully but is not an integer type (e.g. String, Boolean, Float, or a non-integer custom scalar). Count aggregates must return an integer type so the GraphQL schema is coherent, so validation fails with this error.

Source

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

        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> {
        None
    }
}

#[derive(Debug, Eq, PartialEq, Copy, Clone, derive_more::with_trait::Display)]
pub enum CountAggregateType {
    #[display("count")]

View on GitHub (pinned to 724551b9ae)

Solutions

Change the count aggregate's return type to an integer scalar such as Int or BigInt (BigInt is typical for counts).
If a custom scalar is used, make sure it maps to an integer-backed GraphQL type.
Re-apply the metadata after the fix.

Example fix

// before
- name: count_users
  count:
    return_type: { name: Float, arguments: [] }
// after
- name: count_users
  count:
    return_type: { name: BigInt, arguments: [] }

Defensive patterns

Strategy: validation

Validate before calling

const INTEGER_TYPES: &[&str] = &["Int", "BigInt"];
fn is_valid_count_return(rt: &str) -> bool { INTEGER_TYPES.contains(&rt) }

Prevention

Always use Int/BigInt (or an integer-backed custom scalar) for count aggregate return types.
Code-review aggregate definitions when copying from sum/avg aggregates.
Automate a metadata lint rule that count return types are integer scalars.

When it happens

Trigger: Setting the return type of a count or distinct_count aggregate expression to a non-integer scalar (String, Float, Boolean, UUID, etc.) in the metadata.

Common situations: Copy-pasting an aggregate definition from a sum/avg aggregate that legitimately returns Float and forgetting to change the return type; assuming count returns the same type as the counted column; metadata migrations that changed scalar types underneath existing count aggregates.

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/9c5ca816c6a821e4. Report an issue: GitHub.