{"record":{"id":"3f064ad95f5ef68b","repo":"apache/superset","slug":"template-processing-error-error-s","errorCode":null,"errorMessage":"Template processing error: %(error)s","messagePattern":"Template processing error: (.+?)","errorType":"exception","errorClass":"SupersetVirtualTableParseException","httpStatus":400,"severity":"error","filePath":"superset/connectors/sqla/utils.py","lineNumber":129,"sourceCode":"        )\n\n    db_engine_spec = dataset.database.db_engine_spec\n    original_sql = dataset.sql\n    try:\n        sql = dataset.get_template_processor().process_template(\n            original_sql, **dataset.template_params_dict\n        )\n    except SupersetSyntaxErrorException as ex:\n        # ``process_template`` aggregates several jinja2 exceptions\n        # (``TemplateSyntaxError``, ``SecurityError``, ``UndefinedError``,\n        # ``Unicode*Error``) into ``SupersetSyntaxErrorException``. Only\n        # the ``UndefinedError`` case is a \"missing runtime context\"\n        # signal that ``RefreshDatasetCommand`` can safely soften — the\n        # rest (sandbox violations, malformed template syntax, encoding\n        # errors) indicate a real problem with the template that must\n        # surface. See #38012.\n        if isinstance(ex.__cause__, UndefinedError):\n            raise SupersetVirtualTableParseException(\n                message=_(\"Template processing error: %(error)s\", error=str(ex)),\n            ) from ex\n        raise SupersetGenericDBErrorException(\n            message=_(\"Template processing error: %(error)s\", error=str(ex)),\n        ) from ex\n    try:\n        parsed_script = SQLScript(sql, engine=db_engine_spec.engine)\n    except SupersetParseError as ex:\n        # ``SQLScript`` fails on any invalid SQL, including static SQL\n        # with no template dependency. Only soften when the input\n        # contained Jinja markers — in that case an \"Invalid SQL\"\n        # outcome is very likely a rendering artifact (e.g. an empty\n        # ``filter_values('x')`` producing ``WHERE col IN ()``) rather\n        # than a genuine defect in the user's SQL, and the row is\n        # already persisted by ``UpdateDatasetCommand``. Genuinely\n        # invalid static SQL must still hard-error. See #38012.\n        if _has_jinja_markers(original_sql):\n            raise SupersetVirtualTableParseException(","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/apache/superset/blob/f4587218dd19d046c3e4d00063e7d27f8a2ed354/superset/connectors/sqla/utils.py#L111-L147","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["Fix the Jinja syntax in the dataset's SQL (open the dataset editor and validate the template renders).","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.","For UndefinedError-based failures (softened to SupersetVirtualTableParseException), supply the required template_params on the dataset so rendering has its context.","Check the %(error)s detail to identify which of syntax/security/undefined caused it."],"exampleFix":"-- before (virtual dataset sql)\nSELECT * FROM sales WHERE region = '{{ region }\n\n-- after\nSELECT * FROM sales WHERE region = '{{ region }}'","handlingStrategy":"try-catch","validationCode":"from jinja2.sandbox import SandboxedEnvironment\nfrom jinja2 import TemplateSyntaxError\n\ndef dataset_template_valid(sql: str, params: dict | None = None) -> bool:\n    try:\n        SandboxedEnvironment().from_string(sql).render(params or {})\n        return True\n    except TemplateSyntaxError:\n        return False","typeGuard":null,"tryCatchPattern":"from superset.exceptions import (\n    SupersetGenericDBErrorException,\n    SupersetVirtualTableParseException,\n)\n\ntry:\n    cols = get_virtual_table_metadata(dataset)\nexcept SupersetVirtualTableParseException:\n    # UndefinedError: missing runtime context — safe to retry with default params\n    cols = get_virtual_table_metadata_with_defaults(dataset)\nexcept SupersetGenericDBErrorException as ex:\n    if \"Template processing error\" in str(ex):\n        flag_dataset_template_bug(dataset)\n    raise","preventionTips":["Escape non-Superset template braces (dbt, terraform) in dataset SQL.","Provide dataset template_params for any macros the SQL needs at render time.","Distinguish SupersetVirtualTableParseException (missing context, retryable) from SupersetGenericDBErrorException (broken template, must fix)."],"tags":["jinja","virtual-dataset","template","metadata"],"backgroundTag":null,"analyzedSha":"f4587218dd19d046c3e4d00063e7d27f8a2ed354","analyzedAt":"2026-08-14T22:39:27.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}