hasura/graphql-engine · error · RelationshipError

Multiple relationships named {relationship_name} defined for

Error message

Multiple relationships named {relationship_name} defined for type {object_type_name}

What it means

The relationships stage found two relationships with the same name declared on the same qualified object type. Relationship names must be unique per type, so the resolver cannot disambiguate which one to use and errors out. This is a metadata authoring/validation error, not a runtime data error.

Source

Thrown at v3/crates/metadata-resolve/src/stages/relationships/error.rs:13

use crate::types::error::ContextualError;
use crate::types::subgraph::Qualified;
use open_dds::relationships::RelationshipName;
use open_dds::types::CustomTypeName;

#[derive(Debug, thiserror::Error)]
pub enum RelationshipError {
    #[error("Relationship {relationship_name} could not be found for type {object_type_name}")]
    RelationshipNotFound {
        object_type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
    },
    #[error("Multiple relationships named {relationship_name} defined for type {object_type_name}")]
    DuplicateRelationshipForType {
        object_type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
    },

    #[error(
        "Source type {object_type_name} referenced in the definition of relationship {relationship_name} is not defined "
    )]
    RelationshipDefinedOnUnknownType {
        relationship_name: RelationshipName,
        object_type_name: Qualified<CustomTypeName>,
    },
}

impl ContextualError for RelationshipError {
    fn create_error_context(&self) -> Option<error_context::Context> {
        None
    }

View on GitHub (pinned to 724551b9ae)

Solutions

1. Find the duplicate entries for the named type and relationship in metadata files and delete or rename one
2. If the duplicates come from a merge conflict, resolve the conflict keeping a single definition
3. Run metadata validation/lint before apply to catch duplicates early

Example fix

# before
User:
  relationships:
    - name: Address
      targetEntity: Address
    - name: Address
      targetEntity: SecondaryAddress
# after
User:
  relationships:
    - name: Address
      targetEntity: Address
    - name: SecondaryAddress
      targetEntity: SecondaryAddress

fn assert_unique_relationships(rels: &[Relationship]) -> Result<(), String> {
    let mut seen = HashSet::new();
    for r in rels {
        if !seen.insert(r.name.clone()) {
            return Err(format!("duplicate relationship: {}", r.name.0));
        }
    }
    Ok(())
}

catch duplicates during metadata lint: if let Some(RelationshipError::DuplicateRelationshipForType { .. }) = err.downcast_ref() { fail CI with file/line hints }

When it happens

Trigger: Two relationship entries with identical name on the same object type in the OpenDD metadata (duplicate YAML keys, copy-pasted relationship blocks, or merging two metadata files that both define the relationship).

Common situations: Copy-pasting a relationship block and forgetting to change the name; merging branches that both added the same relationship; YAML anchors accidentally duplicating entries.

Related errors

• Relationship {relationship_name} could not be found for type
• Source type {object_type_name} referenced in the definition
• the relationship '{relationship_name}' is defined more than
• the aggregate expression {name} has duplicate definitions of
• Mapping for source field {field_name} already exists in the

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