hasura/graphql-engine · error · ArgumentMappingError

the type {unknown_ndc_type:} is not defined as an object typ

Error message

the type {unknown_ndc_type:} is not defined as an object type in the connector's schema. This type is being mapped to by the type {type_name:} used in argument {argument_name:} which is mapped to the data connector argument {ndc_argument_name:}

What it means

During NDC validation of command/field arguments, the metadata maps a custom object type (type_name) to an NDC type (unknown_ndc_type) that the data connector's schema response does not define as an object type. The resolver checks every type mapping against the connector's /schema capabilities; an object-type mapping to a nonexistent or non-object NDC type raises this error.

Source

Thrown at v3/crates/metadata-resolve/src/helpers/argument.rs:64

    #[error("the mapping for argument {argument_name:} has been defined more than once")]
    DuplicateCommandArgumentMapping { argument_name: ArgumentName },
    #[error("the data connector argument {ndc_argument_name} has been mapped to more than once")]
    DuplicateNdcArgumentMapping {
        ndc_argument_name: DataConnectorArgumentName,
    },
    #[error(
        "the argument {argument_name} is mapped to the data connector argument {ndc_argument_name} which is already used as an argument preset in the DataConnectorLink"
    )]
    ArgumentAlreadyPresetInDataConnectorLink {
        argument_name: ArgumentName,
        ndc_argument_name: DataConnectorArgumentName,
    },
    #[error("{argument_name:} has the data type {data_type:} that has not been defined")]
    UnknownType {
        argument_name: ArgumentName,
        data_type: Qualified<CustomTypeName>,
    },
    #[error(
        "the type {unknown_ndc_type:} is not defined as an object type in the connector's schema. This type is being mapped to by the type {type_name:} used in argument {argument_name:} which is mapped to the data connector argument {ndc_argument_name:}"
    )]
    UnknownNdcType {
        argument_name: ArgumentName,
        ndc_argument_name: DataConnectorArgumentName,
        type_name: Qualified<CustomTypeName>,
        unknown_ndc_type: String,
    },
    #[error("ndc validation error: {0}")]
    NDCValidationError(NDCValidationError),
}

#[derive(Debug, thiserror::Error)]
pub enum ArgumentMappingIssue {
    #[error(
        "the following data connector arguments are not mapped to an argument: {}",
        ndc_argument_names.join(", ")
    )]

View on GitHub (pinned to 724551b9ae)

Solutions

  1. Fetch the connector's current schema (its /schema endpoint or capabilities) and confirm the exact NDC type name exists and is an object type
  2. Update the type mapping in metadata to the correct current NDC type name
  3. If the connector should expose the type, fix the connector or its configuration and refetch the schema
  4. Re-run metadata resolve/build after corrections

Example fix

// before
"type_mappings": [{ "type_name": "my_subgraph.User", "ndc_type": "Usr" }]
// after
"type_mappings": [{ "type_name": "my_subgraph.User", "ndc_type": "User" }]
Defensive patterns

Strategy: validation

Validate before calling

let schema = connector_client.get_schema().await?;
let obj_types: HashSet<&str> = schema.object_types.keys().map(String::as_str).collect();
for m in &type_mappings {
    assert!(obj_types.contains(m.ndc_type.as_str()),
        "NDC object type {} not found in connector schema", m.ndc_type);
}

Type guard

fn ndc_object_type_exists(name: &str, schema: &NdcSchema) -> bool {
    schema.object_types.contains_key(name)
}

Try / catch

Catch UnknownNdcType during resolve and report the mapping triple (type_name -> unknown_ndc_type) with a hint to refetch the connector schema.

Prevention

When it happens

Trigger: A TypeToNdcTypeMapping (or command argument type mapping) points at an NDC object type name that the connector no longer exposes; the connector's schema changed between environments; the mapping string has a typo or wrong capitalization; the connector returns scalar/array types where an object was expected.

Common situations: Connector upgraded and renamed/dropped an object type; environment drift between dev and prod connector schemas; hand-written type mappings in metadata; using a connector whose schema response is incomplete or stale.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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