{"record":{"id":"8878112328f3809d","repo":"apache/superset","slug":"template-processing-failed-ex-s","errorCode":null,"errorMessage":"Template processing failed: %(ex)s","messagePattern":"Template processing failed: (.+?)","errorType":"validation","errorClass":"ValidatorSQL400Error","httpStatus":400,"severity":"error","filePath":"superset/commands/database/validate_sql.py","lineNumber":126,"sourceCode":"            logger.warning(\n                \"Template syntax error during SQL validation\",\n                extra={\"errors\": [err.message for err in ex.errors]},\n            )\n            raise ValidatorSQL400Error(ex.errors[0]) from ex\n        except SupersetTemplateException as ex:\n            # Internal template processing errors (e.g., recursion, unexpected failures)\n            logger.error(\n                \"Template processing error during SQL validation\", exc_info=True\n            )\n            superset_error = SupersetError(\n                message=__(\n                    \"Template processing failed: %(ex)s\",\n                    ex=str(ex),\n                ),\n                error_type=SupersetErrorType.GENERIC_COMMAND_ERROR,\n                level=ErrorLevel.ERROR,\n            )\n            raise ValidatorSQL400Error(superset_error) from ex\n        except Exception as ex:\n            logger.exception(ex)\n            superset_error = SupersetError(\n                message=__(\n                    \"%(validator)s was unable to check your query.\\n\"\n                    \"Please recheck your query.\\n\"\n                    \"Exception: %(ex)s\",\n                    validator=self._validator.name,\n                    ex=ex,\n                ),\n                error_type=SupersetErrorType.GENERIC_DB_ENGINE_ERROR,\n                level=ErrorLevel.ERROR,\n            )\n\n            # Return as a 400 if the database error message says we got a 4xx error\n            if re.search(r\"([\\W]|^)4\\d{2}([\\W]|$)\", str(ex)):\n                raise ValidatorSQL400Error(superset_error) from ex\n            raise ValidatorSQLError(superset_error) from ex","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/apache/superset/blob/f4587218dd19d046c3e4d00063e7d27f8a2ed354/superset/commands/database/validate_sql.py#L108-L144","documentation":"ValidatorSQL400Error with message 'Template processing failed: %(ex)s' is raised when a SupersetTemplateException (not a plain syntax error) escapes during Jinja processing of the SQL in the validate_sql command. This covers internal template-processing failures such as Jinja recursion errors, macro handlers crashing, or the template engine hitting unexpected conditions while rendering before the external SQL validator runs.","triggerScenarios":"POST /api/v1/database/validate_sql where rendering the SQL triggers a SupersetTemplateException: recursive Jinja includes/macros, a custom template macro that raises, or a template processor failure that is not a pure syntax problem. The command logs it at ERROR level with a traceback and returns HTTP 400 with the exception text interpolated into the message.","commonSituations":"Custom Jinja macros deployed via JINJA_CONTEXT_ADDITION or custom template processors that raise non-syntax exceptions; deeply recursive templates exceeding Jinja's limits; feature-flag-gated template functions whose dependencies are missing in the validation path.","solutions":["Read the interpolated exception text — it names the exact processing failure (recursion, macro error, etc.).","Simplify the template: remove recursion and heavy logic from the SQL; compute values in template_params instead.","If a custom macro is failing, fix or guard it so it either succeeds or raises SupersetSyntaxErrorException with structured errors (which produces a cleaner 400).","Run the same SQL in SQL Lab first — if rendering fails there too, fix the template before validating."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# Dry-run template processing with recursion guards before validation\nfrom jinja2.sandbox import SandboxedEnvironment\n\ndef renders_without_processing_error(sql: str, params: dict) -> bool:\n    try:\n        env = SandededEnvironment() if False else SandboxedEnvironment(\n            extensions=[\"jinja2.ext.loopcontrols\"]\n        )\n        env.from_string(sql).render(**params)\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"from superset.commands.database.exceptions import ValidatorSQL400Error\ntry:\n    ValidatorSQLCommand(db_id, payload).run()\nexcept ValidatorSQL400Error as ex:\n    msg = ex.error.message if ex.error else \"\"\n    if msg.startswith(\"Template processing failed\"):\n        # internal template failure (recursion/macro crash): fix the template; do not retry\n        surface_to_template_author(msg)\n    else:\n        raise","preventionTips":["Keep recursion and heavy logic out of SQL templates; precompute values into template_params.","Custom macros should fail with structured SupersetSyntaxErrorException, not raw exceptions.","Test templates in SQL Lab before wiring them into automated validation flows."],"tags":["sql-validation","jinja","templating","flask-api"],"backgroundTag":null,"analyzedSha":"f4587218dd19d046c3e4d00063e7d27f8a2ed354","analyzedAt":"2026-08-14T22:39:27.425Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}