apache/superset · error · QueryObjectValidationError

Error in jinja expression in adhoc column: %(msg)s

Error message

Error in jinja expression in adhoc column: %(msg)s

What it means

QueryObjectValidationError raised in SqlTable._render_adhoc_expression_for_metadata_lookup (models.py:1950) when Jinja rendering of an adhoc column's sqlExpression fails with SupersetSyntaxErrorException. This helper renders templated adhoc column SQL so the result can be matched against column metadata before falling back to literal_column; rendering failures (syntax, sandbox, undefined) abort the query.

Source

Thrown at superset/connectors/sqla/models.py:1950

        return self.make_sqla_column_compatible(sqla_metric, label)

    def _render_adhoc_expression_for_metadata_lookup(
        self,
        sql_expression: str,
        template_processor: BaseTemplateProcessor | None,
    ) -> str:
        """Render Jinja in *sql_expression* so the result can be matched against
        column metadata.  Without this, a templated expression such as
        ``{{ filter_values('x')[0] }}`` is passed raw to ``get_column``, never
        matches, and falls back to ``literal_column`` — which breaks for virtual
        datasets because the rendered name isn't present in the FROM subquery."""
        if not template_processor:
            return sql_expression
        try:
            return template_processor.process_template(sql_expression)
        except SupersetSyntaxErrorException as ex:
            raise QueryObjectValidationError(
                _(
                    "Error in jinja expression in adhoc column: %(msg)s",
                    msg=str(ex),
                )
            ) from ex

    def adhoc_column_to_sqla(  # pylint: disable=too-many-locals
        self,
        col: AdhocColumn,
        force_type_check: bool = False,
        template_processor: BaseTemplateProcessor | None = None,
    ) -> tuple[ColumnElement, utils.GenericDataType | None]:
        """
        Turn an adhoc column into a sqlalchemy column.

        :param col: Adhoc column definition
        :param force_type_check: Should the column type be checked in the db.
               This is needed to validate if a filter with an adhoc column

View on GitHub (pinned to f4587218dd)

Solutions

1. Guard the Jinja so it renders in every context: {{ filter_values('x') | default(['fallback'], true) | first }}.
2. Fix template syntax errors reported in %(msg)s (str(ex) carries the Jinja error detail).
3. If no templating is needed, replace the adhoc column SQL with static SQL or a dataset calculated column.

Example fix

// before (adhoc column)
{ sqlExpression: "CAST({{ filter_values('amt')[0] }} AS BIGINT)" }

// after
{ sqlExpression: "CAST({{ filter_values('amt') | default(['0'], true) | first }} AS BIGINT)" }

from jinja2.sandbox import SandboxedEnvironment

def adhoc_column_renders(sql_expression: str) -> bool:
    try:
        SandboxedEnvironment().from_string(sql_expression).render({})
        return True
    except Exception:
        return False

from superset.exceptions import QueryObjectValidationError

try:
    col, generic_type = table.adhoc_column_to_sqla(adhoc_col, template_processor=processor)
except QueryObjectValidationError as ex:
    if "adhoc column" in str(ex):
        report_bad_chart_expression(adhoc_col, ex)
    raise

When it happens

Trigger: A chart using an adhoc column (Custom SQL column in the groupby/dimension slot, e.g. CAST({{ col }} AS BIGINT) or filter_values-based expressions) whose Jinja fails to render — undefined runtime filters, malformed template, blocked filters.

Common situations: filter_values('x')[0] patterns in adhoc columns when chart context lacks that filter (reports, alerts, other dashboards); typos in template syntax; sandboxed Jinja rejecting previously allowed constructs after upgrade.

Related errors

• Unsupported whisker type: ${whiskerOptions}
• Found invalid orderby options
• Unknown Error
• Please provide both time bounds (Since and Until)
• All values must be numeric

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