hasura/graphql-engine · error · RelationshipError

Source type {object_type_name} referenced in the definition

Error message

Source type {object_type_name} referenced in the definition of relationship {relationship_name} is not defined 

What it means

A relationship definition exists for an object type name that is not present in the resolved types subgraph. The relationships stage looks up the source type of the relationship and fails, meaning the relationship file points at a type that was never defined (or is in a different subgraph/namespace). Note the trailing space in the message is cosmetic.

Source

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

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. Check the object type spelling in the relationship metadata against the actual type definition
2. If the type was renamed, update the relationship's source type
3. Ensure type and relationship metadata live in (or reference) the same subgraph namespace
4. If the type should exist, verify the types stage ran successfully before relationships

Example fix

# before
relationships:
  - sourceType: Usr   # type is defined as 'User'
    name: Address
# after
relationships:
  - sourceType: User
    name: Address

fn check_relationship_source_types(
    types: &BTreeMap<Qualified<CustomTypeName>, ()>,
    rels: &[Relationship],
) -> Result<(), String> {
    for r in rels {
        if !types.contains_key(&r.source_type) {
            return Err(format!("relationship source type {} undefined", r.source_type));
        }
    }
    Ok(())
}

downcast to RelationshipDefinedOnUnknownType and report the missing type name plus the relationship file for quick fixing

When it happens

Trigger: A relationship block whose source object type name doesn't match any Qualified<CustomTypeName> in the types stage output: misspelled type name, type removed, or wrong subgraph/namespace qualification in the metadata.

Common situations: Renaming or deleting an object type without updating its relationships file; putting relationships in a different subgraph than the type; namespace mismatch between the relationship metadata and the type metadata.

Related errors

• Relationship {relationship_name} could not be found for type
• Multiple relationships named {relationship_name} defined for
• the aggregate expression {name} specifies an aggregation fun
• 'globalIdFields' for type {object_type:} found, but no model
• Model {model_name:} is marked as a global ID source but ther

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