hasura/graphql-engine · error · RelationshipError

Model fields cannot be used in command based relationship: {

Error message

Model fields cannot be used in command based relationship: {relationship_name:} on type {type_name:}

What it means

A command-based relationship tried to use model fields (fields from the underlying data model) in its mappings. Command relationships can only reference command arguments and type fields, not model fields directly.

Source

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

        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,
        relationship_name: RelationshipName,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "Model fields cannot be used in command based relationship: {relationship_name:} on type {type_name:}"
    )]
    ModelFieldCannotBeUsedInCommandRelationship {
        relationship_name: RelationshipName,
        type_name: Qualified<CustomTypeName>,
    },
    #[error("Relationships with nested field paths are not supported yet.")]
    NestedFieldPathsNotSupportedYet,
    #[error("{0}")]
    CommandError(#[from] commands::CommandsError),
    #[error("{0}")]
    ModelError(#[from] models::ModelsError),
    #[error("{0}")]
    GraphqlError(#[from] graphql_config::GraphqlConfigError),
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Remove the model-field mappings from the command-based relationship
2. Replace them with mappings from source type fields or command argument mappings
3. If model fields are required, switch the relationship target back to the model

Example fix

// before
relationships:
  author:
    target: { command: AuthorById }
    model_fields: [author_id]  # not allowed
// after
relationships:
  author:
    target: { command: AuthorById }
    argument_mappings:
      author_id: author_id

if (rel.target.command && (rel.model_fields?.length)) {
  throw new Error('model fields cannot be used in a command-based relationship');
}

try { await applyMetadata(md); } catch (e) { if (/cannot be used in command based relationship/.test(e.message)) { /* remove model_fields */ } throw e; }

When it happens

Trigger: Mixing `model_fields`/model-derived fields into a relationship whose target is a CommandName instead of a ModelName.

Common situations: Converting a model-based relationship to a command-based one and leaving model field mappings in place; metadata generated by tools that emit a superset of options.

Related errors

• unknown target command {command_name:} used in relationship
• target argument {argument_name} in argument mapping for rela
• function {function_name} is not defined in data connector {d
• source field {field_name} in field mapping for relationship
• target field {field_name} in field mapping for relationship

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