What causes "Invalid order column: {order_column}" in apache/superset?

apache/superset · error · ValueError

Invalid order column: {order_column}

Error message

Invalid order column: {order_column}

What it means

Raised inside the combined dataset/semantic-view pagination helper in superset/daos/datasource.py when the order_column parameter is not one of the five whitelisted keys in sort_col_map: changed_on, changed_on_delta_humanized, table_name, database.database_name, schema. It is a plain ValueError (not a SupersetException), so unless a caller catches it, it surfaces as an HTTP 500 rather than a 400. The map exists because the sorted query is a UNION of dataset and semantic-view selects that only exposes those aliased columns.

Source

Thrown at superset/daos/datasource.py:198

    @staticmethod
    def paginate_combined_query(
        combined: Any,
        order_column: str,
        order_direction: str,
        page: int,
        page_size: int,
    ) -> tuple[int, list[Any]]:
        """Count, sort, and paginate the combined dataset/semantic-view query."""
        sort_col_map = {
            "changed_on": "changed_on",
            "changed_on_delta_humanized": "changed_on",
            "table_name": "table_name",
            "database.database_name": "database_name",
            "schema": "schema",
        }
        if order_column not in sort_col_map:
            raise ValueError(f"Invalid order column: {order_column}")
        sort_col_name = sort_col_map[order_column]

        total_count = (
            db.session.execute(select(func.count()).select_from(combined)).scalar() or 0
        )

        sort_col = combined.c[sort_col_name]
        ordered_col = sort_col.desc() if order_direction == "desc" else sort_col.asc()

        rows = db.session.execute(
            select(combined.c.item_id, combined.c.source_type)
            .order_by(ordered_col)
            .offset(page * page_size)
            .limit(page_size)
        ).fetchall()

        return total_count, rows

View on GitHub (pinned to f4587218dd)

Solutions

Use only the supported sort keys: 'changed_on', 'changed_on_delta_humanized', 'table_name', 'database.database_name', or 'schema'.
If you need a new sortable column, add it to sort_col_map in the pagination method AND ensure the combined UNION select actually exposes that column, then update API schemas/tests.
As an API caller, validate order_column against the whitelist before issuing the request so you get a clean client-side error instead of a 500.
Check superset-frontend for the dataset list column definitions to confirm which order_column strings it sends.

Example fix

# before
fetch_dataset_page(order_column='name', order_direction='asc')  # ValueError

# after
ALLOWED = {'changed_on', 'changed_on_delta_humanized', 'table_name', 'database.database_name', 'schema'}
col = order_column if order_column in ALLOWED else 'changed_on'
fetch_dataset_page(order_column=col, order_direction=order_direction)

Defensive patterns

Strategy: validation

Validate before calling

SORTABLE_COLUMNS = {
    'changed_on', 'changed_on_delta_humanized',
    'table_name', 'database.database_name', 'schema',
}

def safe_order_column(col: str | None) -> str:
    return col if col in SORTABLE_COLUMNS else 'changed_on'

Type guard

def is_sortable_dataset_column(col: object) -> TypeGuard[str]:
    return col in {
        'changed_on', 'changed_on_delta_humanized',
        'table_name', 'database.database_name', 'schema',
    }

Try / catch

try:
    total, rows = paginate_datasets(combined, order_column, order_direction, page, page_size)
except ValueError as err:
    if 'Invalid order column' in str(err):
        return bad_request(str(err))  # convert DAO ValueError into a 400 response
    raise

Prevention

Validate order_column against a single shared constant used by both frontend and backend.
Treat the sort whitelist as part of the API contract; update schemas and tests when adding columns.
Default invalid sort inputs to 'changed_on' in defensive clients instead of erroring.

When it happens

Trigger: Calling the dataset/semantic-view list API or the underlying DAO pagination method with order_column='name', 'created_on', or any frontend sort field not present in sort_col_map; a custom API client passing an arbitrary column name; frontend changes renaming a table column without updating the backend whitelist.

Common situations: Custom UI skins or forks that add sortable columns to the dataset list; version skew where the frontend sorts on a column the backend whitelist never received; scripts hitting /api/v1/dataset pagination endpoints with hand-built order_column values.

Related errors

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