hasura/graphql-engine · error · RelationshipError

The relationship {relationship_name} on type {type_name} def

Error message

The relationship {relationship_name} on type {type_name} defines an aggregate, but aggregates can only be used with array relationships, not object relationships

What it means

An aggregate definition was found on an object (single-target) relationship, but aggregates only make sense for array relationships where multiple rows can be aggregated.

Source

Thrown at v3/crates/metadata-resolve/src/stages/object_relationships/error.rs:127

        relationship_name: RelationshipName,
    },
    #[error(
        "The target data connector {data_connector_name} for relationship {relationship_name} on type {type_name} does not support the variables capability"
    )]
    RelationshipTargetDoesNotSupportForEach {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        data_connector_name: Qualified<DataConnectorName>,
    },
    #[error(
        "The target data connector {data_connector_name} for relationship {relationship_name} on type {type_name} has not defined any capabilities"
    )]
    NoRelationshipCapabilitiesDefined {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        data_connector_name: Qualified<DataConnectorName>,
    },
    #[error(
        "The relationship {relationship_name} on type {type_name} defines an aggregate, but aggregates can only be used with array relationships, not object relationships"
    )]
    AggregateIsOnlyAllowedOnArrayRelationships {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
    },
    #[error(
        "The aggregate defined on the relationship {relationship_name} on type {type_name} has an error: {error}"
    )]
    ModelAggregateExpressionError {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        error: models::ModelsError, // ideally, this would return the more accurate
                                    // `ModelAggregateExpressionError` instead
    },
    #[error(
        "The source field '{source_field_name}' of type '{source_field_type}' in the relationship '{relationship_name}' on type '{source_type}' cannot be mapped to the target argument '{target_argument_name}' of type '{target_argument_type}' on the target model '{target_model_name}' because their types are incompatible"
    )]

View on GitHub (pinned to 724551b9ae)

Solutions

Remove the aggregate definition from the object relationship
If aggregates are intended, change the relationship to an array relationship so aggregation over many rows is valid

Example fix

// before
relationships:
  author:            # object relationship
    target: { model: authors }
    aggregates:
      count: ...
// after
relationships:
  author:
    target: { model: authors }
# or make it an array relationship:
relationships:
  articles:          # array relationship
    target: { model: articles }
    aggregates:
      count: ...

Defensive patterns

Strategy: validation

Validate before calling

if (rel.aggregates && rel.kind === 'object') {
  throw new Error('aggregates are only allowed on array relationships');
}

Try / catch

try { await applyMetadata(md); } catch (e) { if (/aggregates can only be used with array relationships/.test(e.message)) { /* remove aggregates or make array */ } throw e; }

Prevention

When converting array->object relationships, strip the aggregates block
Codemod lint: aggregates only on relationships with array targets

When it happens

Trigger: Adding an `aggregates` block to a relationship that resolves to a single object rather than an array/collection.

Common situations: Converting an array relationship to an object relationship and leaving the aggregate config behind; misunderstanding that aggregates apply only to collections.

Related errors

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