hasura/graphql-engine · error · ArgumentError

Unknown type: {type_name}

Error message

Unknown type: {type_name}

What it means

Thrown by the metadata-resolve arguments stage when a model or command argument references a type name that is not defined anywhere in the subgraph metadata. During argument resolution every argument's Qualified<CustomTypeName> is looked up in the resolved types collection; a miss yields ArgumentError::UnknownType. It almost always indicates a typo or a missing/failed-to-build OpenDD type definition.

Source

Thrown at v3/crates/metadata-resolve/src/stages/arguments/error.rs:26

#[error("argument '{argument_name}' in {source} has an error: {error}")]
pub struct NamedArgumentError {
    pub source: ArgumentSource,
    pub argument_name: ArgumentName,
    pub error: ArgumentError,
}

impl ContextualError for NamedArgumentError {
    fn create_error_context(&self) -> Option<error_context::Context> {
        self.error.create_error_context()
    }
}

#[derive(Debug, thiserror::Error)]
#[allow(clippy::large_enum_variant)]
pub enum ArgumentError {
    #[error("{0}")]
    BooleanExpressionError(#[from] boolean_expressions::BooleanExpressionError),
    #[error("Unknown type: {type_name}")]
    UnknownType {
        type_name: Qualified<CustomTypeName>,
    },
}

impl ContextualError for ArgumentError {
    fn create_error_context(&self) -> Option<error_context::Context> {
        match self {
            Self::BooleanExpressionError(error) => error.create_error_context(),
            Self::UnknownType { .. } => None,
        }
    }
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the exact type name in the error and fix typos in the argument's type reference (subtype + name)
2. Verify the referenced type is actually declared in the same OpenDD namespace and its file is included in the metadata build
3. If the type was renamed, update all argument declarations that still use the old name
4. Run `ddn build` (or the metadata build step) again to confirm resolution succeeds

Example fix

# before
arguments:
  - name: since
    argumentType: my_sub.My_Typoed_Type
# after
arguments:
  - name: since
    argumentType: my_sub.MyType

// Before building, assert every argument type is declared
fn check_argument_types(declared: &HashSet<String>, args: &[ArgumentDef]) -> Result<(), String> {
    for a in args {
        let q = format!("{}.{}", a.argument_type.subtype, a.argument_type.name);
        if !declared.contains(&q) {
            return Err(format!("argument '{}' references undeclared type '{}'", a.name, q));
        }
    }
    Ok(())
}

// When invoking metadata resolution programmatically
match resolve_metadata(metadata) {
    Err(e @ ArgumentError::UnknownType { .. }) => {
        eprintln!("undeclared type referenced by an argument: {e}");
        // surface to CI and fail the build
    }
    other => other,
}

When it happens

Trigger: Defining a model/command argument in OpenDD YAML whose type points at a Qualified type name that has no corresponding object or scalar type in the same metadata namespace; renaming a type without updating argument declarations; or a plugin/kind extension type whose definition file was not included in the build.

Common situations: Typos in fully-qualified type names (wrong subtype or name), deleting a type still referenced by a command argument, splitting metadata into multiple files and forgetting to include one, or version upgrades that moved types between subtypes.

Related errors

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

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