hasura/graphql-engine · error · BooleanExpressionError::CannotUseFilterExpressionsWithoutSource

a source must be defined for model {model:} in order to use

Error message

a source must be defined for model {model:} in order to use filter expressions

What it means

Filter expressions (filter_by / boolean expression types) can only be applied to models backed by a source; this model has no source configured, so filter expression resolution fails.

Source

Thrown at v3/crates/metadata-resolve/src/stages/boolean_expressions/error.rs:160

    #[error(
        "Scalar representations for data connector '{data_connector_name}' could not found for boolean expression type {boolean_expression_type}"
    )]
    DataConnectorScalarRepresentationsNotFound {
        data_connector_name: Qualified<DataConnectorName>,
        boolean_expression_type: Qualified<CustomTypeName>,
    },

    #[error(
        "Field level comparison operator configuration is not fully supported yet. Please use \"enableAll\":true."
    )]
    FieldLevelComparisonOperatorConfigurationNotSupported,

    #[error(
        "Field level comparison operator configuration is not fully supported yet. Please add all fields in filterable_fields."
    )]
    FieldLevelComparisonOperatorNeedsAllFields,

    #[error("a source must be defined for model {model:} in order to use filter expressions")]
    CannotUseFilterExpressionsWithoutSource { model: Qualified<ModelName> },

    #[error(
        "Target model {model_name:} not found, referenced in relationship {relationship_name:}"
    )]
    TargetModelNotFound {
        relationship_name: RelationshipName,
        model_name: Qualified<ModelName>,
    },

    #[error(
        "Model {model:} has source data connector {model_data_connector:} but its filter expression type {filter_expression_type:} is backed by data connector {filter_expression_data_connector:}"
    )]
    DifferentDataConnectorInFilterExpression {
        model: Qualified<ModelName>,
        model_data_connector: Qualified<DataConnectorName>,
        filter_expression_type: Qualified<CustomTypeName>,
        filter_expression_data_connector: Qualified<DataConnectorName>,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add a source (dataConnector + table/collection) to the model in its metadata
2. If the model is intentionally source-less (e.g. remote/command backed), remove the boolean expression / filter configuration referencing it

Example fix

// before
models:
  Album:
    booleanExpressionType: AlbumFilter
// after
models:
  Album:
    source:
      dataConnectorName: postgres
      table: albums
    booleanExpressionType: AlbumFilter

for (const model of modelsUsingBoolExp(metadata)) {
  if (!model.source) fail(`model ${model.name} needs a source to use filter expressions`);
}

When it happens

Trigger: Attaching a boolean_expression_type or filter expression usage to a model whose metadata has no source (data connector + table/collection) defined.

Common situations: Adding a model that fronts a remote type or command-only model and then referencing it in a filter; a source block was accidentally deleted or never added during metadata authoring.

Related errors

• target source for model '{target_model_name:}' is required t
• source for the following command is defined more than once:
• Error in model permission for model '{model_name}'{}: {error
• unknown field {field_name:} in unique identifier defined for
• unknown field '{field_name:}' used in predicate for type '{t

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