hasura/graphql-engine · error · TypeMappingValidationError

ndc validation error: {0}

Error message

ndc validation error: {0}

What it means

Wrapper error: an NDCValidationError raised while validating the metadata-derived object types against the connector's schema failed to resolve. The inner error (message {0}) carries the actual validation failure detail from the ndc-reference/agent validation layer.

Source

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

        "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,
    },
    #[error("ndc validation error: {0}")]
    NDCValidationError(#[from] NDCValidationError),
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the wrapped NDCValidationError message — it names the concrete validation failure
2. Fix the underlying mismatch it reports (usually a type/field/relationship inconsistency between metadata and connector schema)
3. Re-fetch the connector schema and reapply metadata

// Catch at metadata apply time and surface the inner NDC validation error
try {
  await applyMetadata(md);
} catch (e) {
  if (String(e).includes('ndc validation error')) {
    console.error('NDC validation failed:', e.cause ?? e);
  }
  throw e;
}

When it happens

Trigger: Any mismatch detected when the resolver validates the constructed NDC schema (object types, fields, relationships) against what the data connector reports — for example inconsistent field types, unsupported relationships, or capabilities mismatch.

Common situations: Connector and metadata out of sync; using connector features not declared in the connector's capabilities; malformed custom type definitions.

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

• unable to parse server endpoint: %w
• the type {unknown_ndc_type:} is not defined as an object typ
• the type {unknown_ndc_field_type_name:} is not defined as an
• {errors}
• metadata is not consistent: {error}

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