hasura/graphql-engine · error · TypeCompatibilityIssue

Type '{opendd_type:}' is not compatible with NDC type '{}' -

Error message

Type '{opendd_type:}' is not compatible with NDC type '{}' - {issue_message:}

What it means

A type used in metadata is not compatible with the NDC type it is being compared against, with an issue message explaining why (e.g. incompatible nullability, collection/table vs scalar mismatch, unsupported type). Raised when checking type compatibility between OpenDD type references and NDC types.

Source

Thrown at v3/crates/metadata-resolve/src/helpers/type_validation.rs:6

use crate::stages::data_connector_scalar_types;
use crate::types::subgraph::{QualifiedBaseType, QualifiedTypeName, QualifiedTypeReference};
use ndc_models;

#[derive(Debug, thiserror::Error)]
#[error(
    "Type '{opendd_type:}' is not compatible with NDC type '{}' - {issue_message:}",
    show_ndc_type(ndc_type)
)]
pub struct TypeCompatibilityIssue {
    opendd_type: QualifiedTypeReference,
    ndc_type: ndc_models::Type,
    issue_message: String,
}

/// Validate OpenDd type compatibility with NDC type
pub fn validate_type_compatibility(
    data_connector_scalars: &data_connector_scalar_types::DataConnectorScalars,
    opendd_type: &QualifiedTypeReference,
    ndc_type: &ndc_models::Type,
) -> Option<TypeCompatibilityIssue> {
    validate_type_structure(
        data_connector_scalars,
        &opendd_type.underlying_type,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the issue_message to identify the exact incompatibility and adjust the metadata type (nullability, scalar name, or shape) to match the NDC type
2. Alter the underlying column/type in the database if the metadata is authoritative
3. Refresh the connector schema and reconcile the metadata with the reported types

Example fix

# before
field: { column: email, type: String! }  # NDC type is nullable
# after
field: { column: email, type: String }

fn compatible(opendd: &QualifiedTypeReference, ndc: &ndc_models::Type) -> bool {
    // check nullability and kind align before resolving metadata
    true
}

When it happens

Trigger: Nullability mismatches (nullable metadata type vs non-null NDC type or vice versa); scalar/collection shape mismatch; using a type the connector does not support in that position.

Common situations: Database schema changes altering nullability; connector versions representing types differently; hand-authored mappings with wrong nullability suffixes.

Related errors

• the type of argument '{argument_name:}' is not compatible wi
• unable to parse server endpoint: %w
• error from data source: {}
• Relationship '{name}' is either remote or not having 'relati
• {0}

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