hasura/graphql-engine · error · ModelPermissionError

unknown type {custom_type_name}

Error message

unknown type {custom_type_name}

What it means

UnknownType from the model_permissions stage: a model permission (or its predicate/preset machinery) references a custom object or scalar type name that is not defined in the subgraph's type definitions. The metadata resolver needs every referenced type to exist to resolve permissions.

Source

Thrown at v3/crates/metadata-resolve/src/stages/model_permissions/error.rs:53

    #[error("preset argument '{argument_name}' value has a type error: {type_error}")]
    ModelArgumentValuePresetTypeError {
        argument_name: Spanned<ArgumentName>,
        value_path: JSONPath,
        type_error: typecheck::TypecheckError,
    },

    #[error(
        "a preset argument '{argument_name}' has been set for the model '{model_name}' but no such argument exists for this model"
    )]
    ModelArgumentPresetArgumentNotFound {
        model_name: Spanned<Qualified<ModelName>>,
        argument_name: Spanned<ArgumentName>,
    },

    #[error("in select filter permissions: {error}")]
    SelectFilterPermissionTypePredicateError { error: TypePredicateError },

    #[error("unknown type {custom_type_name}")]
    UnknownType {
        custom_type_name: Qualified<CustomTypeName>,
    },

    #[error("model source is required to resolve relational permissions")]
    ModelSourceRequiredForRelationalPermissions,
    #[error("unknown collection {collection} in data connector {data_connector}")]
    UnknownModelCollection {
        data_connector: Qualified<DataConnectorName>,
        collection: open_dds::data_connector::CollectionName,
    },
    #[error("relational insert is not supported for this model")]
    RelationalInsertNotSupported,
    #[error("relational update is not supported for this model")]
    RelationalUpdateNotSupported,
    #[error("relational delete is not supported for this model")]
    RelationalDeleteNotSupported,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add the missing type definition (object/scalar) named by {custom_type_name} to the subgraph metadata
2. Or fix the reference in the model/permission to point at the existing type name (check subgraph prefix and spelling)
3. Run `ddn build` to confirm all type references resolve

Example fix

# before
# model uses type: default/Users  but no Users type is defined

# after
# add types/users.yaml
kind: ObjectType
version: v1
definition:
  name: Users
  fields: [...]

defined = {f"{subgraph}/{t['definition']['name']}" for t in object_types + scalar_types}
referenced = collect_type_references(models)  # names used by models/permissions
missing = referenced - defined
assert not missing, f'metadata references undefined types: {missing}'

When it happens

Trigger: A model or permission references a Qualified<CustomTypeName> that has no corresponding object type / scalar type definition in the OpenDD metadata, e.g. after deleting a types file or a typo in a type name in model metadata.

Common situations: Renaming types without updating models, partial metadata checkouts, copy-paste across subgraphs leaving dangling type references, ordering of type files vs model files during builds.

Related errors

• Unknown type: {type_name}
• model '{0}'
• command '{0}'
• argument {argument_name:?} has an issue: {issue:?}
• unknown type '{type_name}' used in object boolean expression

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