apache/superset · error · ValidatorSQL400Error

Template processing failed: %(ex)s

Error message

Template processing failed: %(ex)s

What it means

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.

Source

Thrown at superset/commands/database/validate_sql.py:126

            logger.warning(
                "Template syntax error during SQL validation",
                extra={"errors": [err.message for err in ex.errors]},
            )
            raise ValidatorSQL400Error(ex.errors[0]) from ex
        except SupersetTemplateException as ex:
            # Internal template processing errors (e.g., recursion, unexpected failures)
            logger.error(
                "Template processing error during SQL validation", exc_info=True
            )
            superset_error = SupersetError(
                message=__(
                    "Template processing failed: %(ex)s",
                    ex=str(ex),
                ),
                error_type=SupersetErrorType.GENERIC_COMMAND_ERROR,
                level=ErrorLevel.ERROR,
            )
            raise ValidatorSQL400Error(superset_error) from ex
        except Exception as ex:
            logger.exception(ex)
            superset_error = SupersetError(
                message=__(
                    "%(validator)s was unable to check your query.\n"
                    "Please recheck your query.\n"
                    "Exception: %(ex)s",
                    validator=self._validator.name,
                    ex=ex,
                ),
                error_type=SupersetErrorType.GENERIC_DB_ENGINE_ERROR,
                level=ErrorLevel.ERROR,
            )

            # Return as a 400 if the database error message says we got a 4xx error
            if re.search(r"([\W]|^)4\d{2}([\W]|$)", str(ex)):
                raise ValidatorSQL400Error(superset_error) from ex
            raise ValidatorSQLError(superset_error) from ex

View on GitHub (pinned to f4587218dd)

Solutions

1. Read the interpolated exception text — it names the exact processing failure (recursion, macro error, etc.).
2. Simplify the template: remove recursion and heavy logic from the SQL; compute values in template_params instead.
3. 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).
4. Run the same SQL in SQL Lab first — if rendering fails there too, fix the template before validating.

# Dry-run template processing with recursion guards before validation
from jinja2.sandbox import SandboxedEnvironment

def renders_without_processing_error(sql: str, params: dict) -> bool:
    try:
        env = SandededEnvironment() if False else SandboxedEnvironment(
            extensions=["jinja2.ext.loopcontrols"]
        )
        env.from_string(sql).render(**params)
        return True
    except Exception:
        return False

from superset.commands.database.exceptions import ValidatorSQL400Error
try:
    ValidatorSQLCommand(db_id, payload).run()
except ValidatorSQL400Error as ex:
    msg = ex.error.message if ex.error else ""
    if msg.startswith("Template processing failed"):
        # internal template failure (recursion/macro crash): fix the template; do not retry
        surface_to_template_author(msg)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ex.errors[0]
• An unexpected error occurred
• %(validator)s was unable to check your query. Please recheck
• Database not found.
• no SQL validator is configured for %(engine_spec)s

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