hasura/graphql-engine · error · RelationshipError

The source field '{source_field_name}' of type '{source_fiel

Error message

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

What it means

A relationship argument mapping tried to map a source field to a target model argument whose types are incompatible (e.g. mapping a String field to an Int argument). The resolver compares the source field's QualifiedTypeReference with the target argument's type and rejects mismatches.

Source

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

        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,
        target_argument_type: QualifiedTypeReference,
    },
    #[error("Relationship mappings from value expressions are not supported yet.")]
    ValueExpressionMappingsNotSupportedYet,
    #[error(
        "The field path provided in the {location:} of the relationship {relationship_name} on type {type_name} is empty"
    )]
    EmptyFieldPath {
        location: String,

View on GitHub (pinned to 724551b9ae)

Solutions

Compare the source field type and target argument type shown in the message and make them compatible
Change the source field's type or pick a different source field whose type matches
Alter the target model argument type, or add a compatible intermediate field/cast in the source schema

Example fix

// before
// source field: author_id: String
argument_mappings:
  author_id: author_id   # model argument author_id: Int
// after
// change source field type to match:
author_id: Int

Defensive patterns

Strategy: type-guard

Validate before calling

const srcT = types[srcType].fields[m.source]?.type;
const argT = models[targetModel].arguments.find(a => a.name === m.target.argument)?.type;
if (srcT && argT && !typesCompatible(srcT, argT)) throw new Error(`type mismatch: ${srcT} vs ${argT}`);

Type guard

function typesCompatible(a: string, b: string): boolean {
  const norm = (t: string) => t.replace(/^(Int|Float|Numeric|String|Boolean|ID|Uuid|Date|Timestamp).*$/, m => m);
  return norm(a) === norm(b) || (a === 'Int' && b === 'Float') || (a === 'Float' && b === 'Numeric');
}

Try / catch

try { await applyMetadata(md); } catch (e) { if (/types are incompatible/.test(e.message)) { /* align the two named types */ } throw e; }

Prevention

Keep ID column types consistent across schemas (all Int or all UUID)
Validate mapping types with a script that reads both type and model definitions

When it happens

Trigger: Mapping `author_id: String` on the source type to a model argument `author_id: Int` (or any non-castable combination, including object vs scalar mismatches).

Common situations: Underlying database schema changes that alter column types; generating types in a different order so IDs become UUID vs Int; metadata authored by hand without type checking.

Related errors

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