hasura/graphql-engine · error · ArgumentMappingIssue

the type of argument '{argument_name:}' is not compatible wi

Error message

the type of argument '{argument_name:}' is not compatible with the type of the data connector argument '{ndc_argument_name:}': {issue:}

What it means

ArgumentMappingIssue::IncompatibleType reports that an argument mapped to a data connector argument has a type that fails type_validation compatibility checking (type_validation::TypeCompatibilityIssue). Even though both types exist, they cannot be coerced between the metadata-side argument type and the NDC argument type (e.g. comparing an object type against a scalar, or an enum with mismatched values).

Source

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

        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(", ")
    )]
    UnmappedNdcArguments {
        ndc_argument_names: Vec<DataConnectorArgumentName>,
    },
    #[error(
        "the type of argument '{argument_name:}' is not compatible with the type of the data connector argument '{ndc_argument_name:}': {issue:}"
    )]
    IncompatibleType {
        argument_name: ArgumentName,
        ndc_argument_name: DataConnectorArgumentName,
        issue: type_validation::TypeCompatibilityIssue,
    },
}

impl ShouldBeAnError for ArgumentMappingIssue {
    fn should_be_an_error(&self, flags: &open_dds::flags::OpenDdFlags) -> bool {
        match self {
            ArgumentMappingIssue::UnmappedNdcArguments { .. } => false,
            ArgumentMappingIssue::IncompatibleType { .. } => {
                flags.contains(open_dds::flags::Flag::ValidateArgumentMappingTypes)
            }
        }
    }

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the nested {issue} detail from type_validation to see which part of the types clashed
2. Change the argument's type or the mapping so both sides agree (same scalar representation or a valid object-type mapping)
3. If the connector's type changed, update the mapping or connector version so types align
4. Add/adjust an intermediate type mapping so the custom type maps to the correct NDC type

Example fix

// before
// argument "limit" typed as custom object type mapped to NDC scalar Int
// after
// argument "limit" typed as built-in Integer mapped to NDC scalar Int

for m in argument_mappings {
    type_validation::check_compatibility(&arg_type, &ndc_type)
        .map_err(|issue| format!("{} vs {}: {issue}", m.argument_name, m.ndc_argument_name))?;
}

fn types_compatible(a: &TypeReference, b: &NdcType) -> bool {
    type_validation::check_compatibility(a, b).is_ok()
}

Catch IncompatibleType and use the nested TypeCompatibilityIssue to tell the user exactly which sub-check failed (scalar representation, nullability, etc.).

When it happens

Trigger: An ArgumentToDataConnectorArgumentMapping where the argument's Hasura type and the NDC argument's declared type fail the compatibility rules in type_validation (object vs scalar, mismatched scalar representation, incompatible nullable/array wrappers); changing an argument's type after the mapping was created; connector changing an argument from scalar to object type.

Common situations: Type drift between metadata and connector schema; mapping a new object-typed argument to what is actually a scalar NDC argument; connector version upgrades that alter argument types.

Related errors

• the following data connector arguments are not mapped to an
• argument {argument_name} is not defined for collection {coll
• argument {argument_name} is not defined for function/procedu
• unable to parse server endpoint: %w
• the type {unknown_ndc_type:} is not defined as an object typ

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