hasura/graphql-engine · error · RelationshipError

unknown target model {model_name:} used in relationship {rel

Error message

unknown target model {model_name:} used in relationship {relationship_name:} on type {type_name:}

What it means

A relationship on a custom object type references a target model that is not defined in the metadata, so the relationship cannot be resolved.

Source

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

    commands::CommandName,
    data_connector::DataConnectorName,
    models::ModelName,
    relationships::RelationshipName,
    types::{CustomTypeName, FieldName},
};

#[derive(Debug, thiserror::Error)]
pub enum RelationshipError {
    #[error(
        "duplicate relationship field {field_name} from {relationship_name} associated with source type {type_name}"
    )]
    DuplicateRelationshipFieldInSourceType {
        field_name: ast::Name,
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
    },

    #[error(
        "unknown target model {model_name:} used in relationship {relationship_name:} on type {type_name:}"
    )]
    UnknownTargetModelUsedInRelationship {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        model_name: Qualified<ModelName>,
    },

    #[error(
        "unknown target command {command_name:} used in relationship {relationship_name:} on type {type_name:}"
    )]
    UnknownTargetCommandUsedInRelationship {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        command_name: Qualified<CommandName>,
    },

    #[error(

View on GitHub (pinned to 724551b9ae)

Solutions

1. Define the missing target model in metadata
2. Fix the model name (including qualification) in the relationship
3. If the model moved to another metadata source, reference it correctly or remove the relationship

Example fix

# before
relationships:
  - name: author
    target_model: { target: authors, type: models }  # typo
# after
relationships:
  - name: author
    target_model: { target: author, type: models }

for rel in &type.relationships {
    assert!(models.contains_key(&rel.target_model), "unknown target model {}", rel.target_model);
}

When it happens

Trigger: relationship target's model name is misspelled, refers to a model in another subgraph not present, or the model was deleted/renamed.

Common situations: Renaming or removing models without updating relationships; splitting metadata across files and forgetting to include the target model; typos in qualified model names.

Related errors

• the relationship '{relationship_name}' is defined more than
• the comparable relationship '{relationship_name}' for the op
• the comparable relationship '{relationship_name}' for the op
• relationship '{relationship_name}' is used in comparableRela
• the comparable relationship '{name}' is defined more than on

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