hasura/graphql-engine · error · TypeMappingValidationError

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:}

What it means

Thrown during metadata resolution when a Hasura custom type maps to a data connector object type name that does not exist in the connector's NDC schema. The resolver fetched the connector's schema (via its capabilities/schema endpoint) and could not find the declared NDC type name, so the mapping from the custom type cannot be honored.

Source

Thrown at v3/crates/metadata-resolve/src/stages/object_types/error.rs:120

        field_name: FieldName,
    },
    #[error(
        "the type {unknown_field_type_name:} referenced by the field {field_name:} in type {type_name:} has not been defined"
    )]
    UnknownFieldType {
        type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
        unknown_field_type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "could not find mappings for {object_type_name:} to the {data_connector_object_type:} on data connector {data_connector_name:}"
    )]
    DataConnectorTypeMappingNotFound {
        object_type_name: Qualified<CustomTypeName>,
        data_connector_name: Qualified<DataConnectorName>,
        data_connector_object_type: DataConnectorObjectType,
    },
    #[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:}"
    )]
    UnknownNdcType {
        type_name: Qualified<CustomTypeName>,
        unknown_ndc_type: DataConnectorObjectType,
    },
    #[error("expected to find a predicate type for argument {argument_name:} but did not")]
    PredicateTypeNotFound { argument_name: ArgumentName },
    #[error(
        "the type {unknown_ndc_field_type_name:} is not defined as an object type in the connector's schema. This type is referenced by the field {ndc_field_name:} in the connector's schema type {ndc_type_name:}, which is mapped to the field {field_name:} in the type {type_name:}"
    )]
    UnknownNdcFieldObjectType {
        type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
        ndc_type_name: String,
        ndc_field_name: String,
        unknown_ndc_field_type_name: String,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the exact object type name in the connector's NDC schema response (e.g. query the connector's /schema) and correct data_connector_object_type in the metadata
2. Check that the metadata's data source URL points at the connector instance whose schema actually contains this type
3. If the connector was upgraded/renamed types, update the metadata mappings to the new names
4. Regenerate/refresh the tracked tables so the connector schema and metadata stay in sync

Example fix

// before
{"object_type_name":"users","data_connector_object_type":"user"}
// after
{"object_type_name":"users","data_connector_object_type":"users"}

// Before applying metadata, check the connector's schema for the type name
const ndcSchema = await fetch(`${connectorUrl}/schema`).then(r => r.json());
const ok = Object.keys(ndcSchema.object_types ?? {}).includes(metadataType.data_connector_object_type);
if (!ok) throw new Error(`NDC type '${metadataType.data_connector_object_type}' not in connector schema`);

When it happens

Trigger: Defining a CustomTypes object type with a data_connector_object_type mapping whose NDC type name is misspelled, was renamed in the connector, or the connector schema was fetched from a stale/different connector; e.g. mapping 'User' to 'users' when the connector exposes 'User' or 'user_table'.

Common situations: Typo in the ndc object type name in metadata; connector upgraded and renamed table/type names; pointing metadata at a different connector data source; connector schema endpoint returning fewer types than expected (permissions or filtered schema).

Related errors

• the type {unknown_ndc_field_type_name:} is not defined as an
• ndc validation error: {0}
• field '{field_name}' of type '{type_name}' used in a field c
• {error:} in type {type_name:}
• unable to parse server endpoint: %w

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