feat(context): warn when load_result returns None during parse phase (#11070) - #12815

Fixes #11070.

What

Extends ProviderContext.load_result in core/dbt/context/providers.py so that when it's about to return None for a name that was never stored, and the provider is in parse mode (self.provider.execute is False), it fires a JinjaLogWarning pointing the user at the {% if execute %} docs.

Why

Quoting @joellabes on the issue:

Any Jinja that relies on a result being returned from the database will error during the parse phase. For example [...]

Encountered an error:
Compilation Error in model order_payment_methods (models/order_payment_methods.sql)
'None' has no attribute 'table'

and the alternative suggestion:

we could also add a warning line inside of run_query and friends so you wind up with something like this:

WARN: run_query was invoked in the model order_payment_methods, but dbt is currently not running in execute mode so accessing the result will fail. Wrap in an if execute block https://docs.getdbt.com/reference/dbt-jinja-functions/execute

@graciegoheen on 2026-03-10:

Good call! This would definitely help improve debugging.

(Also noting that #12736, a prior attempt, was self-closed by @claygeo on 2026-03-30 for queue management, not on merits — so the direction is still open.)

Where

The run_query macro path is:

1. User calls {% set r = run_query(sql) %} in a model.
2. run_query (defined in dbt-adapters) calls {% call statement("run_query_statement", ...) %} and then load_result("run_query_statement").
3. During parse, execute is False, statement()'s body is skipped, nothing is stored.
4. load_result("run_query_statement") drops into the else branch of ProviderContext.load_result in dbt-core and returns None.
5. User code dereferences None.table / None.columns → the cryptic compile error.

That else branch is a narrow, dbt-core-owned choke point that sees every run_query call during parse, which is why it's a better hook than trying to patch run_query or statement in dbt-adapters.

Diff summary

else:
    # Handle trying to load a result that was never stored.
    #
    # During the parse phase `execute == False`, so no SQL has been run
    # and `sql_results` is always empty. A `load_result` call that
    # lands here is almost always a user who forgot to wrap an
    # introspective query (e.g. `run_query` / `load_result`) in an
    # `{% if execute %}` block — which later surfaces as the cryptic
    # "'None' has no attribute 'table'" compilation error. Emit an
    # upfront warning pointing at the execute docs so the root cause
    # is visible before the downstream error.
    #
    # See dbt-labs/dbt-core#11070.
    if not self.provider.execute:
        model_name = getattr(self.model, "name", None) or getattr(
            self.model, "unique_id", "<unknown>"
        )
        fire_event(
            JinjaLogWarning(
                msg=(
                    f"`load_result('{name}')` was called in {model_name} during "
                    "the parse phase and returned None because no SQL has been "
                    "run yet. Wrap introspective calls like `run_query` / "
                    "`load_result` in an `{% if execute %}` block — see "
                    "https://docs.getdbt.com/reference/dbt-jinja-functions/execute"
                )
            )
        )
    return None

Uses the same fire_event(JinjaLogWarning(msg=...)) pattern already used in store_seed_results a few hundred lines below, so no new imports are needed.

Behaviour

• Parse phase + name not stored → warns (this is the new behaviour, targeting the reported bug).
• Execute phase + name not stored → unchanged: returns None silently. A missing name in execute mode is a real user bug (typo, or calling load_result on a name never wrapped in a statement block) and should not be converted into a spurious "wrap in execute" warning.
• Both phases + name in sql_results → completely unchanged.

Tests

• No unit test added in this PR — the existing tests/unit/context/test_context.py only validates the set of keys available on the context, and there's no existing load_result behavioral test harness. Adding one would require spinning up a full ProviderContext with model fixtures; happy to add that in a follow-up if a maintainer prefers.
• Smoke-tested the branch logic with a minimal fake ProviderContext (parse + unknown name → warns; execute + unknown name → no warn; _sql_results-present branches unchanged).
• python -m py_compile core/dbt/context/providers.py passes.

Changelog

Added .changes/unreleased/Features-20260411-184500.yaml via the standard changie format.