fix(engine): actionable error when a Jinja field is missing/None/empty

[nabinchha]

Summary

Closes #629.

Empty-render and missing-attribute Jinja failures used to surface as the same unhelpful message:

🛑 Failed to process column 'preferred_english_name': User provided prompt generation template is invalid.

Two distinct failure modes were collapsing into that generic string:

• Bug 1 — empty render (e.g. {{ person.preferred_english_name }} where the key is missing): _assert_rendered_text_not_empty raised a descriptive UserTemplateError, but sanitize_user_exceptions then replaced the message with the generic one.
• Bug 3 — raw UndefinedError (e.g. {{ person.address.street }} where address is missing): a jinja2.exceptions.UndefinedError leaked all the way up because the sanitizer only caught UserTemplateError / TemplateSyntaxError.

Both paths now raise a new EmptyTemplateRenderError(UserTemplateError) subclass that the sanitizer is explicitly told to pass through. The exception carries an actionable, row-level message naming the offending chain plus copy-pasteable Jinja conditional and SkipConfig remediation patterns:

Template rendered to empty text. This usually happens when one or more
referenced fields are missing, None, or empty in this row.

Likely culprits in this row:
  - person.address.street (missing from record)

To handle missing values, you can:

  1. Provide a fallback in your template using a Jinja conditional:
       {{ person.address.street if person.address else 'N/A' }}

  2. Skip rows where required fields are missing using SkipConfig:
       skip=SkipConfig(when="{{ not person.address }}")

The "gate" expression in the suggestions stops one accessor past the resolvable prefix so it stays safe to evaluate (avoiding a fresh UndefinedError on the suggested fix itself).

What changed

packages/data-designer-engine/src/data_designer/engine/processing/ginja/:

• exceptions.py — new EmptyTemplateRenderError subclass.
• ast.py — new public helpers ast_extract_access_chains and resolve_access_chain (plus an AccessChain type alias).
• environment.py:
  • _assert_rendered_text_not_empty / validate_rendered_text thread the template + record through and raise the new error with the per-row diagnostic.
  • UserTemplateSandboxEnvironment.safe_render catches UndefinedError and converts it to the same EmptyTemplateRenderError. NativeJinjaSandboxEnvironment.render_template mirrors the conversion for consistency.
  • sanitize_user_exceptions bypasses EmptyTemplateRenderError (same treatment as UserTemplateUnsupportedFiltersError).

End-to-end propagation already prepends the column name via _run_batch, so no other layers needed changes.

Test plan

• New regression tests for both bugs (test_empty_render_raises_empty_template_render_error_with_culprit_chain, test_undefined_nested_attr_raises_empty_template_render_error_with_safe_gate).
• Coverage for the "resolved-to-None" / "resolved-to-empty-string" / multi-culprit branches.
• Test that the sanitizer no longer collapses the new error to the generic message.
• Test that NativeJinjaSandboxEnvironment also converts UndefinedError.
• Parametrized coverage for ast_extract_access_chains (plain text, single name, nested attr, subscript, mixed, dynamic subscript skipped, loop/conditional context) and resolve_access_chain (resolved, partially-resolved, type-mismatch cases).
• Happy-path render still works; one image-cell-generator test was updated from match="invalid" to match="empty" to reflect the new (more informative) message.
• uv run pytest packages/data-designer-engine/tests/engine/processing/ginja/ — 95 passed.
• uv run ruff format + uv run ruff check — clean.

[github-actions]

PR #633 Review — fix(engine): actionable error when a Jinja field is missing/None/empty

Summary

Closes #629. Two distinct failure modes in Jinja rendering used to collapse into the same unhelpful "User provided prompt generation template is invalid." message:

1. Empty render — template like {{ person.preferred_english_name }} where the key is missing on the record.
2. Raw UndefinedError — template like {{ person.address.street }} where person.address is missing, leaking Jinja's internal "'dict object' has no attribute 'address'".

The PR introduces EmptyTemplateRenderError(UserTemplateError) and teaches sanitize_user_exceptions to pass it through unaltered. Both the secure (UserTemplateSandboxEnvironment.safe_render) and native (NativeJinjaSandboxEnvironment.render_template) engines now convert UndefinedError + empty-render cases to this new error, which carries a row-level diagnostic naming culprit chains and giving copy-pasteable Jinja-conditional and SkipConfig remediation patterns. Two new AST helpers (ast_extract_access_chains, resolve_access_chain) back the culprit detection.

Findings

Correctness

• Exception chaining inconsistency (minor). NativeJinjaSandboxEnvironment.render_template uses raise EmptyTemplateRenderError(...) from exception (environment.py:248-251), preserving the original UndefinedError in __cause__. UserTemplateSandboxEnvironment.safe_render re-raises without from exception (environment.py:402). The messages are curated so there's no user-visible difference, but __cause__ is useful when someone is debugging from a traceback. Recommend raise EmptyTemplateRenderError(...) from exception in safe_render too.
• _build_empty_render_message fallback path is robust. Wrapping parser(user_template) + ast_extract_access_chains(...) in try/except Exception and falling back to a generic message avoids masking the original render failure. Good defensive posture.
• resolve_access_chain list bounds. Correctly rejects out-of-bounds indices (acc >= len(current) or acc < -len(current)). Negative literal subscripts (e.g. {{ items[-1] }}) would reach resolve_access_chain as int accessors through _build_access_chain, and Python's native negative indexing on current[acc] handles them. Good.
• Dict/list/scalar branching is complete. isinstance(current, dict), isinstance(current, list), fallthrough else — the three cases cover the sanitized record value types.
• Gate expression derivation is safe. The one-past-resolvable-prefix slice (sample_accessors[: len(sample_prefix) + 1]) yields a Jinja Undefined leaf on evaluation, which stringifies to "" and is falsy — doesn't re-trigger UndefinedError. This is subtle; the inline comment at environment.py explains the reasoning clearly.
• culprits[0] for the remediation suggestion. Only the first culprit becomes the template for the remediation example. With multiple culprits listed in the bullets, a user might fix only the first and rerun. Arguably OK (they'll iterate), but consider noting "(showing fix for first culprit)" if user feedback reports confusion.
• Sanitizer order. sanitize_user_exceptions now catches (UserTemplateUnsupportedFiltersError, EmptyTemplateRenderError) before (UserTemplateError, TemplateSyntaxError). Since Python matches except clauses in order and both are UserTemplateError subclasses, the ordering is load-bearing. Correct as written. A short comment noting "ordering matters — these are UserTemplateError subclasses" would help future maintainers.
• Dynamic subscripts. _build_access_chain returns None for a[b]-style chains, and the visitor descends into the subscript expression with in_chain=False, extracting b as its own chain. Matches the docstring behavior and the parametrized test coverage.

Project conventions

• from __future__ import annotations present in all new/modified files ✓
• Absolute imports only ✓
• Modern type syntax (list[str], str | None, AccessChain = tuple[str, list[str | int]]) ✓
• Type annotations on all new public callables ✓
• EmptyTemplateRenderError subclasses UserTemplateError, preserving the canonical-error-at-boundaries invariant from AGENTS.md ✓
• New AST helpers land in ginja/ast.py alongside existing helpers; _build_access_chain is private — good separation.
• Module-level _CULPRIT_* sentinels are fine, but a small Enum or Literal type alias would make the classifier signature self-documenting. Not worth blocking on.

Tests

• 95 tests in ginja/ passing per the PR description; diff shows thorough new coverage:
  • test_ast.py: parametrized chain-extraction (plain, nested, subscript, mixed, dynamic-subscript skip, loop/conditional context), parametrized resolve_access_chain (fully resolved, partially resolved, type-mismatch, list bounds).
  • test_environment.py: both bug regressions, culprit-classification branches (missing / None / empty string), multi-culprit listing, sanitizer-bypass assertion, native-engine parity, happy path, skip_template_validation=True path.
• The image-cell-generator test was updated from match="invalid" to match="empty" with an explanatory comment pointing at issue Cryptic "User provided prompt generation template is invalid" error when a referenced template field is empty or missing #629. Good — this is exactly the kind of test churn worth annotating.
• Gap (small): No test asserts the fallback message when _build_empty_render_message's parse branch fails (e.g., a monkey-patched parser that throws). The code path exists (environment.py:346-352) but is not covered. Arguably not worth chasing given how defensive it is.
• Gap (small): No test for a chain with a non-identifier string key rendered via [...] bracket notation (e.g. {{ data["weird key"] }}). _format_access_chain has the branch; a parametrized case would close the loop.

Performance

• Culprit detection runs only on the error path. It reparses user_template once per failure. Negligible.
• ast_extract_access_chains is O(n) in AST size; visit does no backtracking.

Security

• No new attack surface. The helpers operate on already-sanitized records and the existing trusted parse path.
• The curated error message embeds user data (record keys in the access chain) into the exception string. This is the same blast radius as prior UserTemplateError messages — acceptable.

Documentation

• Docstrings on new helpers are thorough and accurate. safe_render's docstring is updated to mention EmptyTemplateRenderError. ✓
• Inline comments explain the non-obvious bits (top-level chain extraction, safe gate derivation, why the sanitizer bypasses this error class).

Suggested follow-ups (non-blocking)

1. Add from exception to the UndefinedError → EmptyTemplateRenderError re-raise in UserTemplateSandboxEnvironment.safe_render for traceback consistency with the native engine path.
2. Consider a one-line comment on the sanitize_user_exceptions except-clause noting that ordering is load-bearing.
3. Add a test case for non-identifier string subscripts in _format_access_chain.
4. If user reports come in about the multi-culprit case being ambiguous, consider labelling the remediation example ("fix for first culprit shown").

Verdict

Approve with minor nits. The change is well-scoped, well-tested, and genuinely fixes the reported bug class (both the "empty render" and "undefined nested attr" variants) without expanding blast radius. Exception taxonomy and sanitizer bypass are implemented correctly. The nits above are small-cost polish; none block merge.

[greptile-apps]

Greptile Summary

This PR fixes two error-reporting bugs in Jinja template rendering: empty renders and UndefinedError on nested attribute access both now surface as EmptyTemplateRenderError with a row-level diagnostic that names the offending field and provides copy-pasteable Jinja conditional and SkipConfig remediation patterns.

• Adds EmptyTemplateRenderError(UserTemplateError) subclass and updates sanitize_user_exceptions to pass it through, alongside a new _build_empty_render_message helper that parses the template AST, resolves access chains against the live record, and constructs a safe gate expression for the suggested fix.
• Catches UndefinedError in both UserTemplateSandboxEnvironment.safe_render and NativeJinjaSandboxEnvironment.render_template, converting it to the actionable error instead of leaking the raw Jinja message.
• Adds comprehensive regression tests (including two new tests for the previously-reviewed gate-expression safety edge case where the root variable is entirely absent from the record).

Confidence Score: 5/5

Safe to merge — both bug fixes are well-scoped, the exception hierarchy change is backwards-compatible, and the gate-expression logic is correct across all resolution cases.

The UndefinedError conversion and empty-render diagnostic paths are thoroughly tested, including the previously-flagged missing-root edge case now covered by two dedicated regression tests. The culprit classification, access-chain resolution, and gate-chain construction all handle the full range of record shapes (missing root, partially-resolved dict, None leaf, empty collection) without generating unsafe suggested templates. The sanitizer bypass is ordered correctly relative to the parent-class clause.

No files require special attention.

Important Files Changed

Filename	Overview
packages/data-designer-engine/src/data_designer/engine/processing/ginja/exceptions.py	Adds EmptyTemplateRenderError as a UserTemplateError subclass; clean, minimal change to the exception hierarchy.
packages/data-designer-engine/src/data_designer/engine/processing/ginja/ast.py	Adds ast_extract_access_chains, resolve_access_chain, and _build_access_chain; AST traversal logic correctly handles top-level chains, dynamic subscripts, and partial resolution.
packages/data-designer-engine/src/data_designer/engine/processing/ginja/environment.py	Adds UndefinedError → EmptyTemplateRenderError conversion in both sandbox environments, threads user_template/record through validate_rendered_text, and adds _build_empty_render_message with correct gate-expression logic for all resolution cases.
packages/data-designer-engine/tests/engine/processing/ginja/test_environment.py	Comprehensive regression tests covering both bugs, all culprit classification branches, sanitizer bypass, native engine conversion, safe remediation templates, and loop-variable scoping.
packages/data-designer-engine/tests/engine/processing/ginja/test_ast.py	Parametrized tests for ast_extract_access_chains and resolve_access_chain covering plain text, nested attrs, subscripts, dynamic subscripts, and type-mismatch cases.
packages/data-designer-engine/tests/engine/column_generators/generators/test_image.py	Updates match string from "invalid" to "empty" to reflect the more informative EmptyTemplateRenderError message; correct and minimal change.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant WithJinja2 as WithJinja2UserTemplateRendering
    participant Env as UserTemplateSandboxEnvironment
    participant Msg as _build_empty_render_message
    participant Sanitizer as sanitize_user_exceptions

    Caller->>WithJinja2: render_template(record)
    Note over WithJinja2: @sanitize_user_exceptions
    WithJinja2->>Env: safe_render(user_template, record)
    
    alt Empty render (field is None/empty/missing)
        Env->>Env: template.render(record) → ""
        Env->>Env: validate_rendered_text("", user_template, record)
        Env->>Msg: _build_empty_render_message(template, record, parse)
        Msg-->>Env: actionable message with culprit chains
        Env-->>WithJinja2: raise EmptyTemplateRenderError
    else UndefinedError (nested missing attr)
        Env->>Env: template.render(record) → UndefinedError
        Env->>Msg: _build_empty_render_message(template, record, parse)
        Msg-->>Env: actionable message with culprit chains
        Env-->>WithJinja2: raise EmptyTemplateRenderError
    end

    Note over WithJinja2,Sanitizer: EmptyTemplateRenderError passes through (not swallowed)
    WithJinja2-->>Sanitizer: EmptyTemplateRenderError propagates
    Sanitizer-->>Caller: re-raises EmptyTemplateRenderError as-is

Loading

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into fix/template-re..." | Re-trigger Greptile}

[greptile-apps]

Gate expression is one step too deep when the root variable is absent from the record

resolve_access_chain returns (False, None, []) both when the root name is missing from record (name not in record) and when the first accessor fails — both yield prefix = []. The gate computation sample_accessors[:len(sample_prefix)+1] therefore produces sample_accessors[:1] in either scenario. For {{ person.address.street }} with record = {}, that gives gate_chain = "person.address", so the suggestion becomes {{ person.address.street if person.address else 'N/A' }}. But in Jinja2, person is Undefined when it is absent from the context, and Undefined.__getattr__ raises UndefinedError immediately — the suggested template itself fails with the same kind of error the user is trying to fix.

The gate should fall back to the root name alone (gate_accessors = []) when sample_name is not present in record.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer-engine/src/data_designer/engine/processing/ginja/environment.py
Line: 736-737

Comment:
**Gate expression is one step too deep when the root variable is absent from the record**

`resolve_access_chain` returns `(False, None, [])` both when the root name is missing from `record` (`name not in record`) and when the first accessor fails — both yield `prefix = []`. The gate computation `sample_accessors[:len(sample_prefix)+1]` therefore produces `sample_accessors[:1]` in either scenario. For `{{ person.address.street }}` with `record = {}`, that gives `gate_chain = "person.address"`, so the suggestion becomes `{{ person.address.street if person.address else 'N/A' }}`. But in Jinja2, `person` is `Undefined` when it is absent from the context, and `Undefined.__getattr__` raises `UndefinedError` immediately — the suggested template itself fails with the same kind of error the user is trying to fix.

The gate should fall back to the root name alone (`gate_accessors = []`) when `sample_name` is not present in `record`.

How can I resolve this? If you propose a fix, please make it concise.

[nabinchha]

Fixed in 6d258f1. When sample_name is not in record, the gate now falls back to the root name alone (gate_accessors = []) instead of slicing one accessor past an empty prefix. The resulting suggestion ({{ person.address.street if person else 'N/A' }} / SkipConfig(when="{{ not person }}")) is safe to evaluate because Jinja's default Undefined is falsy and stringifies to "", whereas Undefined.__getattr__ raises.

Added two regression tests covering this exact scenario:

• test_undefined_root_variable_produces_safe_remediation_template — asserts the suggested template uses the root-name-only gate (and does not include the broken .address accessor).
• test_undefined_root_variable_remediation_template_is_renderable — actually renders the suggested template against {} and verifies it returns 'N/A' instead of raising, which would have caught the original bug.