hasura/graphql-engine · error · RelationshipError

unknown target command {command_name:} used in relationship

Error message

unknown target command {command_name:} used in relationship {relationship_name:} on type {type_name:}

What it means

Thrown during metadata resolution when an object relationship on a custom type references a target command (via `command_name`) that does not exist in the resolved metadata. The resolver validates every relationship target before building the resolved metadata graph.

Source

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

    #[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(
        "source field {field_name} in field mapping for relationship {relationship_name} on type {source_type} is unknown."
    )]
    UnknownSourceFieldInRelationshipMapping {
        source_type: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        field_name: FieldName,
    },
    #[error(
        "target field {field_name} in field mapping for relationship {relationship_name} on type {source_type} to model {model_name} is unknown."

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the exact qualified command name (including subgraph) in the relationship's target matches an existing command in your metadata
2. If the command was renamed/deleted, update the relationship target to point to an existing command or remove the relationship
3. Check that the subgraph portion of the Qualified<CommandName> matches where the command is actually defined

Example fix

// before
relationships:
  author:
    target:
      command: my_subgraph/GetAuthor  # command does not exist
// after
relationships:
  author:
    target:
      command: my_subgraph/AuthorById  # existing command name

// before applying metadata, assert the command exists
const rel = metadata.types['article'].relationships['author'];
const cmdKey = rel.target.command; // e.g. "subgraph/Command"
const exists = metadata.commands?.[cmdKey] !== undefined ||
  Object.keys(metadata.commands||{}).some(k => k.endsWith('/' + cmdKey));
if (!exists) throw new Error(`relationship targets unknown command: ${cmdKey}`);

try { await applyMetadata(md); } catch (e) { if (String(e.message).includes('unknown target command')) { /* surface which relationship/command */ } throw e; }

When it happens

Trigger: Defining an object relationship in metadata whose target is a CommandName that was never declared, was renamed, or lives under a different subgraph/namespace than the one used in the relationship definition.

Common situations: Renaming or deleting a command without updating relationships that target it; typos in the command name; moving a command to a different subgraph while relationships still use the old qualified name; ordering issues where the command is defined in a different metadata file that is not being merged.

Related errors

• target argument {argument_name} in argument mapping for rela
• Model fields cannot be used in command based relationship: {
• function {function_name} is not defined in data connector {d
• the relationship '{relationship_name}' is defined more than
• the comparable relationship '{relationship_name}' for the op

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