apache/superset · error · SupersetVirtualTableParseException

Template processing error: %(error)s

Error message

Template processing error: %(error)s

What it means

Raised in get_virtual_table_metadata (utils.py:129) when Jinja rendering of a virtual dataset's SQL fails with SupersetSyntaxErrorException. The exception is classified: if the cause is jinja2 UndefinedError it becomes SupersetVirtualTableParseException (a soft, retryable-with-context signal used by RefreshDatasetCommand); all other template failures (TemplateSyntaxError, sandbox SecurityError, Unicode errors) become SupersetGenericDBErrorException because they indicate a genuinely broken template (see issue #38012).

Solutions

1. Fix the Jinja syntax in the dataset's SQL (open the dataset editor and validate the template renders).
2. If the braces are not meant for Superset (dbt-style {{ ref(...) }}, terraform templating), escape or remove them so the Jinja engine does not interpret them.
3. For UndefinedError-based failures (softened to SupersetVirtualTableParseException), supply the required template_params on the dataset so rendering has its context.
4. Check the %(error)s detail to identify which of syntax/security/undefined caused it.

Example fix

-- before (virtual dataset sql)
SELECT * FROM sales WHERE region = '{{ region }

-- after
SELECT * FROM sales WHERE region = '{{ region }}'

from jinja2.sandbox import SandboxedEnvironment
from jinja2 import TemplateSyntaxError

def dataset_template_valid(sql: str, params: dict | None = None) -> bool:
    try:
        SandboxedEnvironment().from_string(sql).render(params or {})
        return True
    except TemplateSyntaxError:
        return False

from superset.exceptions import (
    SupersetGenericDBErrorException,
    SupersetVirtualTableParseException,
)

try:
    cols = get_virtual_table_metadata(dataset)
except SupersetVirtualTableParseException:
    # UndefinedError: missing runtime context — safe to retry with default params
    cols = get_virtual_table_metadata_with_defaults(dataset)
except SupersetGenericDBErrorException as ex:
    if "Template processing error" in str(ex):
        flag_dataset_template_bug(dataset)
    raise

When it happens

Trigger: A virtual dataset whose sql contains malformed Jinja ({{ unclosed, unknown tag), a sandboxed-Jinja security violation, or a Unicode/encoding problem — raised whenever Superset fetches metadata for that dataset (open in Explore, dataset list, refresh metadata command).

Common situations: Typos in dataset Jinja; templates referencing macros not available in dataset scope; Jinja sandbox restrictions introduced/tightened in newer Superset releases; copy-pasted SQL with template braces from other tooling (e.g. dbt) that Superset tries to render.

Related errors

• Error in jinja expression in fetch values predicate: %(msg)s
• Virtual dataset query cannot be empty
• A valid color scheme is required
• Error in jinja expression in adhoc column: %(msg)s
• Error in jinja expression in column expression: %(msg)s

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/3f064ad95f5ef68b. Report an issue: GitHub.

Appendix: source

Thrown at superset/connectors/sqla/utils.py:129

        )

    db_engine_spec = dataset.database.db_engine_spec
    original_sql = dataset.sql
    try:
        sql = dataset.get_template_processor().process_template(
            original_sql, **dataset.template_params_dict
        )
    except SupersetSyntaxErrorException as ex:
        # ``process_template`` aggregates several jinja2 exceptions
        # (``TemplateSyntaxError``, ``SecurityError``, ``UndefinedError``,
        # ``Unicode*Error``) into ``SupersetSyntaxErrorException``. Only
        # the ``UndefinedError`` case is a "missing runtime context"
        # signal that ``RefreshDatasetCommand`` can safely soften — the
        # rest (sandbox violations, malformed template syntax, encoding
        # errors) indicate a real problem with the template that must
        # surface. See #38012.
        if isinstance(ex.__cause__, UndefinedError):
            raise SupersetVirtualTableParseException(
                message=_("Template processing error: %(error)s", error=str(ex)),
            ) from ex
        raise SupersetGenericDBErrorException(
            message=_("Template processing error: %(error)s", error=str(ex)),
        ) from ex
    try:
        parsed_script = SQLScript(sql, engine=db_engine_spec.engine)
    except SupersetParseError as ex:
        # ``SQLScript`` fails on any invalid SQL, including static SQL
        # with no template dependency. Only soften when the input
        # contained Jinja markers — in that case an "Invalid SQL"
        # outcome is very likely a rendering artifact (e.g. an empty
        # ``filter_values('x')`` producing ``WHERE col IN ()``) rather
        # than a genuine defect in the user's SQL, and the row is
        # already persisted by ``UpdateDatasetCommand``. Genuinely
        # invalid static SQL must still hard-error. See #38012.
        if _has_jinja_markers(original_sql):
            raise SupersetVirtualTableParseException(

View on GitHub (pinned to f4587218dd)