hasura/graphql-engine · error · NDCValidationError

type {0} is not defined in the agent schema

Error message

type {0} is not defined in the agent schema

What it means

A type referenced in mappings or capabilities is not present in the agent (sub)graph's type schema. The NDC validation stage resolves every referenced type name against the set of types declared in OpenDD metadata.

Source

Thrown at v3/crates/metadata-resolve/src/helpers/ndc_validation.rs:95

    )]
    ColumnTypeDoesNotMatch {
        db_name: DataConnectorName,
        model_name: ModelName,
        field_name: FieldName,
        collection_name: CollectionName,
        column_name: DataConnectorColumnName,
        field_type: String,
        column_type: String,
    },
    #[error(
        "internal error: data connector does not define the scalar type {type}, used by field {field_name} in model {model_name}"
    )]
    TypeCapabilityNotDefined {
        model_name: ModelName,
        field_name: FieldName,
        r#type: String,
    },
    #[error("type {0} is not defined in the agent schema")]
    NoSuchType(String),
    #[error("mapping for type {type_name} of model {model_name} is not defined")]
    UnknownModelTypeMapping {
        model_name: Qualified<ModelName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error("mapping for type {type_name} of command {command_name} is not defined")]
    UnknownCommandTypeMapping {
        command_name: Qualified<CommandName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "Field {field_name} for type {type_name} referenced in model {model_name} is not defined"
    )]
    UnknownTypeField {
        model_name: ModelName,
        type_name: CustomTypeName,
        field_name: FieldName,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Declare the missing type (add the corresponding type definition to the metadata)
2. Fix the reference to point at an existing, correctly-spelled type name
3. Search the metadata for all usages of the type name and ensure the definition exists in the same subgraph

Example fix

# before
# referenced: type: app.User  (no such type defined)
# after
kind: ObjectType
apiVersion: graphql.hasura.io/v1alpha1
metadata:
  name: User
  ...

fn type_defined(name: &QualifiedTypeName, types: &TypeSet) -> bool { types.contains(name) }

When it happens

Trigger: Referencing a custom type name in a model/command mapping that is not declared by any Type/ObjectType definition; misspelling a type name; deleting a type definition while it is still referenced.

Common situations: Renaming or removing an object type without updating references; ordering issues where a type is expected but was never authored; copy-paste errors in type names.

Related errors

• error while parsing the endpoint :%w
• failed to get version from server: %w
• cannot read config from file/env: %w
• no such field on type {type_name}: {field_name}
• unable to parse server endpoint: %w

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