hasura/graphql-engine · error · RelationshipError

Relationship {relationship_name} could not be found for type

Error message

Relationship {relationship_name} could not be found for type {object_type_name}

What it means

Thrown by the metadata-resolve relationships stage when an OpenDD relationship is referenced (e.g. from a model command or another metadata object) but no relationship with that name is defined on the specified custom object type. Resolution walks the types subgraph and fails to find the relationship entry, so metadata resolution aborts. It almost always indicates a dangling reference after a rename or deletion in the metadata files.

Source

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

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>,
    },
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Grep all metadata files for the exact relationship name shown in the error and fix the typo or stale reference
2. If the relationship was renamed, update the referencing object (model/command) to the new name
3. If the relationship was deleted intentionally, remove the now-dangling reference
4. Re-run metadata resolve/build to confirm the types subgraph now contains the relationship

Example fix

# before
objects:
  User:
    relationships:
      - name: Adress   # typo; referencing metadata says 'Address'
        targetEntity: Address
# after
objects:
  User:
    relationships:
      - name: Address
        targetEntity: Address

// before resolving/apply: assert every referenced relationship exists
fn check_relationship_refs(
    types: &BTreeMap<Qualified<CustomTypeName>, ObjectTypeWithRelationships>,
    refs: &[(Qualified<CustomTypeName>, RelationshipName)],
) -> Result<(), String> {
    for (ty, rel) in refs {
        let found = types.get(ty)
            .and_then(|t| t.relationships.iter().find(|r| &r.name == rel));
        if found.is_none() {
            return Err(format!("relationship {rel} not found on type {ty}"));
        }
    }
    Ok(())
}

if let Err(e) = resolve_metadata(&metadata) {
    if let Some(RelationshipError::RelationshipNotFound { object_type_name, relationship_name }) = e.downcast_ref() {
        eprintln!("stale relationship ref: {relationship_name} on {object_type_name}");
    }
}

When it happens

Trigger: Metadata files reference a relationship by name on a Qualified<CustomTypeName> (e.g. a model relationship entry or command argument mapping) that does not exist in the object type's relationships map. Typical triggers: renaming a relationship in types but not in dependent metadata, typos in the relationship name, or applying only part of a metadata change set.

Common situations: Splitting/renaming relationships across PRs where the referencing file lands first; copying metadata between subgraphs with different type definitions; YAML/JSON indentation mistakes that silently drop the relationships block.

Related errors

• Multiple relationships named {relationship_name} defined for
• Source type {object_type_name} referenced in the definition
• 'globalIdFields' for type {object_type:} found, but no model
• Model {model_name:} is marked as a global ID source but ther
• the relationship '{relationship_name}' is defined more than

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