{"record":{"id":"bb17ccfe2c1192a7","repo":"hasura/graphql-engine","slug":"unknown-target-command-command-name-used-in-rel","errorCode":null,"errorMessage":"unknown target command {command_name:} used in relationship {relationship_name:} on type {type_name:}","messagePattern":"unknown target command (.+?) used in relationship (.+?) on type (.+?)","errorType":"validation","errorClass":"RelationshipError","httpStatus":null,"severity":"error","filePath":"v3/crates/metadata-resolve/src/stages/object_relationships/error.rs","lineNumber":33,"sourceCode":"    #[error(\n        \"duplicate relationship field {field_name} from {relationship_name} associated with source type {type_name}\"\n    )]\n    DuplicateRelationshipFieldInSourceType {\n        field_name: ast::Name,\n        type_name: Qualified<CustomTypeName>,\n        relationship_name: RelationshipName,\n    },\n\n    #[error(\n        \"unknown target model {model_name:} used in relationship {relationship_name:} on type {type_name:}\"\n    )]\n    UnknownTargetModelUsedInRelationship {\n        type_name: Qualified<CustomTypeName>,\n        relationship_name: RelationshipName,\n        model_name: Qualified<ModelName>,\n    },\n\n    #[error(\n        \"unknown target command {command_name:} used in relationship {relationship_name:} on type {type_name:}\"\n    )]\n    UnknownTargetCommandUsedInRelationship {\n        type_name: Qualified<CustomTypeName>,\n        relationship_name: RelationshipName,\n        command_name: Qualified<CommandName>,\n    },\n\n    #[error(\n        \"source field {field_name} in field mapping for relationship {relationship_name} on type {source_type} is unknown.\"\n    )]\n    UnknownSourceFieldInRelationshipMapping {\n        source_type: Qualified<CustomTypeName>,\n        relationship_name: RelationshipName,\n        field_name: FieldName,\n    },\n    #[error(\n        \"target field {field_name} in field mapping for relationship {relationship_name} on type {source_type} to model {model_name} is unknown.\"","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/metadata-resolve/src/stages/object_relationships/error.rs#L15-L51","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the exact qualified command name (including subgraph) in the relationship's target matches an existing command in your metadata","If the command was renamed/deleted, update the relationship target to point to an existing command or remove the relationship","Check that the subgraph portion of the Qualified<CommandName> matches where the command is actually defined"],"exampleFix":"// before\nrelationships:\n  author:\n    target:\n      command: my_subgraph/GetAuthor  # command does not exist\n// after\nrelationships:\n  author:\n    target:\n      command: my_subgraph/AuthorById  # existing command name","handlingStrategy":"validation","validationCode":"// before applying metadata, assert the command exists\nconst rel = metadata.types['article'].relationships['author'];\nconst cmdKey = rel.target.command; // e.g. \"subgraph/Command\"\nconst exists = metadata.commands?.[cmdKey] !== undefined ||\n  Object.keys(metadata.commands||{}).some(k => k.endsWith('/' + cmdKey));\nif (!exists) throw new Error(`relationship targets unknown command: ${cmdKey}`);","typeGuard":null,"tryCatchPattern":"try { await applyMetadata(md); } catch (e) { if (String(e.message).includes('unknown target command')) { /* surface which relationship/command */ } throw e; }","preventionTips":["Generate relationship targets from the same source of truth as command definitions","Run metadata lint/CI validation before applying","Search for command usages before renaming or deleting a command"],"tags":["metadata","relationships","command","validation","hasura"],"backgroundTag":"metadata-relationship-validation-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}