hasura/graphql-engine · error · Error

no such type defined in the document: {0}

Error message

no such type defined in the document: {0}

What it means

Thrown when a document references a type name that is not defined in the schema, e.g. a fragment type condition `on DeletedType` or a directive/variable/argument type referencing a missing type. Produced by get_type_info in validation/collect.rs:110 when type lookup fails during validation. It signals schema/document mismatch rather than a malformed selection per se.

Source

Thrown at v3/crates/graphql/lang-graphql/src/validation/error.rs:39

    #[error("fragment of type {fragment_type} cannot be spread on type {selection_type}")]
    FragmentCannotBeSpread {
        selection_type: ast::TypeName,
        fragment_type: ast::TypeName,
    },
    // TODO, this error isn't thrown yet
    #[error(
        "a selection set is specified on field '{field_name}' of non-composite type: {type_name}"
    )]
    SelectionOnNonCompositeType {
        field_name: ast::Name,
        type_name: ast::TypeName,
    },
    #[error("no such field on type {type_name}: {field_name}")]
    NoFieldOnType {
        type_name: ast::TypeName,
        field_name: ast::Name,
    },
    #[error("no such type defined in the document: {0}")]
    UnknownType(ast::TypeName),
    #[error("an internal error occurred during validation: type lookup failed for {type_name}")]
    InternalTypeNotFound { type_name: ast::TypeName },
    #[error(
        "an internal error occurred during validation: field {field_name} lookup failed for sub type '{sub_type_name}' of type '{type_name}'"
    )]
    InternalNoFieldOnSubtype {
        type_name: ast::TypeName,
        sub_type_name: ast::TypeName,
        field_name: ast::Name,
    },
    #[error(
        "different fields {field1} and {field2} cannot be merged under the same alias: {alias}"
    )]
    FieldsConflictDifferentFields {
        alias: ast::Alias,
        field1: ast::Name,
        field2: ast::Name,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the type name spelling in fragment type conditions and directives against the schema
2. Regenerate the client/query from the schema version the server actually serves
3. If you own the schema, keep a deprecation window instead of hard-removing types used by clients

Example fix

// before
fragment F on Usr { id }
// after
fragment F on User { id }

for name in referenced_type_names(doc) { assert!(schema.has_type(&name), "unknown type {name}"); }

fn type_exists(schema: &Schema, name: &str) -> bool { schema.lookup_type(name).is_some() }

match validate(doc) { Err(Error::UnknownType(t)) => fail_fast_with_schema_diff(t), r => r }

When it happens

Trigger: Fragment `on` conditions naming types absent from the schema; queries generated against a different (older/newer) schema; renamed or removed types after schema evolution; typos in type condition names.

Common situations: Deploying a client built against a newer schema than the server; removing/renaming schema types server-side while stale persisted queries still reference them; multi-environment schema drift.

Related errors

• validation failed: {0}
• Unexpected value: expecting {expected_kind:}, but found: {fo
• '{name:}' is not a valid GraphQL name.
• '{alias:} is not a valid alias
• {value} is not a valid limit value

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