hasura/graphql-engine · error · TypePredicateError

the source data connector {data_connector:} for type {type_n

Error message

the source data connector {data_connector:} for type {type_name:} has not been defined

What it means

The type's source is configured to use a data connector that has not been defined in metadata. Every model/type that is backed by a data source must reference a data connector declared at the subgraph level; an undeclared connector name fails resolution.

Source

Thrown at v3/crates/metadata-resolve/src/types/error.rs:432

        "unknown field '{field_name}' for type '{type_name}' used in target mapping for relationship '{relationship_name}'"
    )]
    UnknownFieldInModelRelationshipTargetMapping {
        field_name: FieldName,
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
    },
    #[error("boolean expression '{boolean_expression_name:}' not found")]
    BooleanExpressionNotFound {
        boolean_expression_name: Qualified<CustomTypeName>,
    },
    #[error(
        "field '{field_name:}' could not be found in boolean expression type for object type '{type_name:}'"
    )]
    BooleanExpressionFieldNotFound {
        field_name: Spanned<FieldName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "the source data connector {data_connector:} for type {type_name:} has not been defined"
    )]
    UnknownTypeDataConnector {
        type_name: Qualified<CustomTypeName>,
        data_connector: Qualified<DataConnectorName>,
    },
    #[error(
        "field '{field_name}' of type '{type_name}' used in a field comparison has the unknown NDC type '{ndc_type_name}' and therefore cannot be compared to a single value"
    )]
    UnsupportedFieldComparisonToUnknownType {
        field_name: Spanned<FieldName>,
        field_type: QualifiedTypeReference,
        type_name: Qualified<CustomTypeName>,
        ndc_type_name: ndc_models::TypeName,
    },

    #[error(
        "field '{field_name}' of type '{type_name}' used in a field comparison is an array type and therefore cannot be compared to a single value"

View on GitHub (pinned to 724551b9ae)

Solutions

Check `data_connector` in the message and declare a data connector with exactly that qualified name in the same subgraph
Update the model's source to reference the existing connector name
Verify the subgraph prefix in the qualified name matches where the connector is declared
Ensure all metadata files defining connectors are included when building the subgraph

Example fix

# before
data_connectors: {}
models:
  users:
    source: {dataConnectorName: postgres}   # undefined
# after
data_connectors:
  postgres:
    uri: {file: ./connectors/postgres/config.json}
models:
  users:
    source: {dataConnectorName: postgres}

Defensive patterns

Strategy: validation

Validate before calling

// Verify the connector is declared before resolving
if !metadata.data_connectors.contains_key(&data_connector_name) {
    return Err(format!("data connector {data_connector_name} not defined"));
}

Type guard

fn connector_defined<'a>(md: &'a Metadata, n: &Qualified<DataConnectorName>) -> Option<&'a DataConnectorLink> {
    md.data_connectors.get(n)
}

Try / catch

if let Err(Error::UnknownTypeDataConnector { type_name, data_connector }) = result {
    return Err(format!("declare connector {data_connector} for {type_name}'s source"));
}

Prevention

Declare all connectors in the same build as the models that use them
Use a single source of truth for connector names across environments

When it happens

Trigger: Setting a model's `dataConnectorName` (source) to a connector that isn't declared under `data_connectors`; renaming a connector without updating model sources; missing connector definition after splitting metadata files.

Common situations: Env-specific metadata where the connector is defined in a different file that wasn't loaded; typos in the qualified connector name; migrating between connector versions that renamed the connector.

Related errors

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