apache/superset · error · ColumnNotFoundException

Column not found

Error message

Column not found

What it means

ColumnNotFoundException("Column not found") raised in adhoc_column_to_sqla's probe path (models.py:2055). For adhoc columns, Superset probes the datasource with a SELECT of the expression and inspects the result columns; when get_columns_description returns an empty list — the expression yields no columns, i.e. the referenced column genuinely does not exist — this error is thrown. Real DB/connectivity failures propagate as SupersetGenericDBErrorException instead; only a true empty probe result maps here.

Source

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

                else:
                    qry = sa.select(sqla_column).where(sa.false()).select_from(tbl)
                sql = self.database.compile_sqla_query(
                    qry,
                    catalog=self.catalog,
                    schema=self.schema,
                )
                # A real DB/connectivity failure during the probe surfaces as a
                # SupersetGenericDBErrorException from get_columns_description and
                # is allowed to propagate unchanged; only a genuine empty result
                # (the column truly isn't there) is a ColumnNotFoundException.
                col_desc = get_columns_description(
                    self.database,
                    self.catalog,
                    self.schema or None,
                    sql,
                )
                if not col_desc:
                    raise ColumnNotFoundException(message="Column not found")
                is_dttm = col_desc[0]["is_dttm"]  # type: ignore
                # ResultSet already resolves the generic type from the
                # driver's cursor.description; reuse it so callers can
                # coerce filter values correctly (e.g. numeric IN-lists
                # stay unquoted for numeric adhoc expressions like
                # CAST(... AS BIGINT)).
                generic_type = col_desc[0].get("type_generic")

        if is_dttm and has_timegrain:
            sqla_column = self.db_engine_spec.get_timestamp_expr(
                col=sqla_column,
                pdf=pdf,
                time_grain=time_grain,
            )
        return self.make_sqla_column_compatible(sqla_column, label), generic_type

    def _get_series_orderby(
        self,

View on GitHub (pinned to f4587218dd)

Solutions

1. Verify the column exists in the dataset: refresh dataset metadata (dataset editor > Refresh) and confirm the column is listed.
2. Fix the adhoc column expression or chart to reference an existing column name.
3. If the underlying table changed, sync the dataset (re-save or force metadata refresh) so Superset's column list matches reality.
4. Catch ColumnNotFoundException when resolving dynamic column expressions so callers can present a field-mapping error.

Example fix

// before (chart dimension)
{ sqlExpression: 'usr_id' } // column was renamed to user_id

// after
{ sqlExpression: 'user_id' }

def column_exists_in_dataset(dataset, column_name: str) -> bool:
    return any(c.column_name == column_name for c in dataset.columns)

from superset.connectors.sqla.models import ColumnNotFoundException

try:
    sqla_col, generic_type = table.adhoc_column_to_sqla(adhoc_col)
except ColumnNotFoundException:
    table = refresh_dataset_metadata(table)  # sync columns, then retry once
    sqla_col, generic_type = table.adhoc_column_to_sqla(adhoc_col)

When it happens

Trigger: Chart payload with an adhoc column referencing a column name not present in the (virtual) dataset, e.g. sqlExpression 'unknown_col' or a templated expression rendering to a name absent from the FROM subquery. The probe query SELECT unknown_col ... returns no column description, so the error is raised client-side of the engine.

Common situations: Dataset schema changed (column renamed/dropped) while charts still reference the old name; virtual datasets whose Jinja renders column names dynamically; mismatch between the physical table and cached dataset metadata after DDL.

Related errors

• Dataset metric not found.
• Error in jinja expression in column expression: %(msg)s
• Error in jinja expression in datetime column: %(msg)s
• Error in jinja expression in metric expression: %(msg)s
• Error in jinja expression in adhoc column: %(msg)s

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