hasura/graphql-engine · error · RelationshipError

The aggregate defined on the relationship {relationship_name

Error message

The aggregate defined on the relationship {relationship_name} on type {type_name} has an error: {error}

What it means

The aggregate expression attached to a relationship failed to resolve; the underlying error comes from the models resolution stage (ModelsError) and is embedded in this message. Typical causes are invalid operator references, unknown fields, or type mismatches in the aggregate expression.

Source

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

        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"
    )]
    ModelArgumentTargetMappingTypeMismatch {
        source_type: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        source_field_name: FieldName,
        source_field_type: QualifiedTypeReference,
        target_model_name: Qualified<ModelName>,
        target_argument_name: ArgumentName,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the embedded {error} detail — it carries the actual ModelsError reason
2. Fix the aggregate expression per that inner error (correct function, field, or type)
3. Verify the target model/connector supports the aggregate functions you use

Example fix

// before
aggregates:
  total:
    count: { field: created_at }   # unsupported/invalid usage
// after
aggregates:
  total:
    count: {}
  latest:
    max: { field: created_at }

// best effort: ensure referenced aggregate fields exist on the target model
const modelFields = new Set(models[targetModel].fields.map(f => f.name));
for (const agg of Object.values(rel.aggregates ?? {})) {
  for (const f of agg.fields ?? []) if (!modelFields.has(f)) throw new Error(`aggregate references unknown field ${f}`);
}

try { await applyMetadata(md); } catch (e) { if (/aggregate .* has an error/.test(e.message)) { /* inspect embedded ModelsError detail */ } throw e; }

When it happens

Trigger: Defining an aggregate whose expression (functions/operators, field references, or result type) cannot be resolved against the target model's supported aggregate capabilities.

Common situations: Using an aggregate function the target connector/model doesn't support; referencing a non-numeric field with a numeric aggregate; malformed expression trees.

Related errors

• target field {field_name} in field mapping for relationship
• target argument {argument_name} in argument mapping for rela
• The relationship {relationship_name} on type {type_name} def
• the relationship '{relationship_name}' is defined more than
• the comparable relationship '{relationship_name}' for the op

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