apache/superset · error · ValidatorSQL400Error

ex.errors[0]

Error message

ex.errors[0]

What it means

At superset/commands/database/validate_sql.py:112 the handler for SupersetSyntaxErrorException passes ex.errors[0] into ValidatorSQL400Error. SupersetSyntaxErrorException is raised when Jinja template rendering of the SQL fails (invalid Jinja2 syntax, undefined variables) and it carries a list of SupersetError objects with details like line numbers. The indexer ex.errors[0] selects the first error to surface as an HTTP 400; if the exception was constructed with an empty errors list, this line itself raises IndexError.

Source

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

            # process_template() renders Jinja2 templates and always returns a
            # new string (does not mutate the input SQL). May raise
            # SupersetSyntaxErrorException for template syntax errors or
            # SupersetTemplateException for internal errors.
            sql = template_processor.process_template(sql, **template_params)

            timeout = app.config["SQLLAB_VALIDATION_TIMEOUT"]
            timeout_msg = f"The query exceeded the {timeout} seconds timeout."
            with utils.timeout(seconds=timeout, error_message=timeout_msg):
                errors = self._validator.validate(sql, catalog, schema, self._model)
            return [err.to_dict() for err in errors]
        except SupersetSyntaxErrorException as ex:
            # Template syntax errors (e.g., invalid Jinja2 syntax, undefined variables)
            # These contain detailed error information including line numbers
            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=__(

View on GitHub (pinned to f4587218dd)

Solutions

1. Fix the Jinja2 syntax in the submitted SQL: balanced {{ }} / {% %}, valid filter names, and default values for variables (e.g., {{ my_var }} declared in template_params or with a |default filter).
2. Pass matching `template_params` in the request body for every variable referenced in the SQL.
3. If you raise SupersetSyntaxErrorException from custom template code, always construct it with at least one SupersetError so ex.errors[0] is defined.
4. Check the warning log ('Template syntax error during SQL validation') — it lists all error messages, which pinpoints the exact line.

Example fix

{% raw %}
-- before (undefined variable, bad filter)
SELECT * FROM tbl WHERE d > {{ start_date | dataz }}

-- after
SELECT * FROM tbl WHERE d > '{{ start_date | default("2020-01-01") }}'
{% endraw %}

# Render the template client-side of the API before submitting for validation
from superset.jinja_context import get_template_processor

def template_is_renderable(sql: str, database, template_params: dict) -> bool:
    try:
        get_template_processor(database=database).process_template(
            sql, **(template_params or {})
        )
        return True
    except Exception:
        return False

from superset.commands.database.exceptions import (
    ValidatorSQL400Error, ValidatorSQLError,
)
try:
    result = ValidatorSQLCommand(db_id, {"sql": sql, "template_params": params}).run()
except ValidatorSQL400Error as ex:
    # 400: syntax/template problem in the submitted SQL — show message, no retry
    display(ex.error.message if ex.error else str(ex))
except ValidatorSQLError as ex:
    # 422: validator backend failure — safe to retry once
    retry_once()

When it happens

Trigger: POST /api/v1/database/validate_sql with a `sql` payload containing malformed Jinja2 (e.g., unclosed {{, bad filter syntax) or references to undefined template variables; supplying `template_params` whose keys don't match the placeholders used in the SQL. Programmatically, raising SupersetSyntaxErrorException(errors=[]) makes line 112 fail with IndexError.

Common situations: Migrating SQL Lab queries with template markers from other tools; enabling Jinja templating (FEATURE_FLAGS) and using macros with typos; custom code in superset/jinja_context.py or custom template processors that raise SupersetSyntaxErrorException without an errors payload.

Related errors

• Template processing failed: %(ex)s
• 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/6cd5d6e7ada430ea. Report an issue: GitHub.