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).

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)

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
• Please call with an object. Example: `stringify myObj`
• Invalid JSON string: ${String(error)}
• A valid color scheme is required

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