What causes "invalid return value" in dbt-labs/dbt-core?

Verify the schema name and database arguments — NULL results usually mean the query matched nothing.

dbt-labs/dbt-core · error · minijinja::Error

invalid return value

Error message

invalid return value

What it means

check_schema_exists runs a query expecting the scalar result to be exactly 0 (schema absent) or 1 (schema present). Any other value — None from an empty result set, or an integer outside {0,1} — raises a minijinja ReturnValue error 'invalid return value'. It indicates the query did not return the expected boolean probe result.

Source

Thrown at crates/dbt-adapter/src/adapter/adapter_impl.rs:1671

            None::<String>,
        )
        .with_quoting(Policy::falses());

        let (package_name, macro_name) = self.check_schema_exists_macro(state, &[])?;
        let batch = execute_macro_wrapper_with_package(
            state,
            &[
                RelationObject::new(Arc::new(info_schema)).into_value(),
                Value::from(schema),
            ],
            &macro_name,
            &package_name,
        )?;

        match batch.first_value_as_i64() {
            Some(0) => Ok(Value::from(false)),
            Some(1) => Ok(Value::from(true)),
            _ => Err(minijinja::Error::new(
                minijinja::ErrorKind::ReturnValue,
                "invalid return value",
            )),
        }
    }

    #[allow(clippy::too_many_arguments)]
    pub fn get_relations_by_pattern(
        &self,
        state: &State,
        schema_pattern: &str,
        table_pattern: &str,
        exclude: Option<&str>,
        database: Option<&str>,
        quote_table: Option<bool>,
        excluded_schemas: Option<Value>,
    ) -> Result<Value, minijinja::Error> {
        // Validate excluded_schemas if provided

View on GitHub (pinned to 0267ce9170)

Solutions

Verify the schema name and database arguments — NULL results usually mean the query matched nothing.
Check the adapter supports the probe query (information_schema / catalog lookups).
Inspect the query built for the adapter and run it manually to see what scalar it returns.
Catch the error and treat it as 'schema unknown' if your macro can tolerate it.

Defensive patterns

Strategy: try-catch

Try / catch

{% try %}
  {% set exists = check_schema_exists(schema, database) %}
{% except %}
  {% set exists = none %}
{% endtry %}

Prevention

Pass correct, correctly-cased schema and database names
Run the underlying probe query manually on the target warehouse before relying on it
Confirm the adapter implements the catalog probe your macro assumes

When it happens

Trigger: Calling check_schema_exists against a database whose COUNT/information_schema probe returns NULL (no rows) or a value other than 0/1 — e.g. wrong database argument causing the probe query to return nothing.

Common situations: Pointing at a database where the probe SQL is not valid or returns no rows; custom adapters that don't support the expected information_schema query; quoting/casing issues in the schema name producing unexpected results.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

AI-assisted analysis of dbt-labs/dbt-core@0267ce9170 (2026-09-07). Data as JSON: /api/errors/90161a5266591714. Report an issue: GitHub.