apache/superset · error · InvalidPayloadSchemaError

INVALID_PAYLOAD_SCHEMA_ERROR

INVALID_PAYLOAD_SCHEMA_ERROR

Error message

An error happened when validating the request

What it means

Raised by the table_metadata endpoint when the query string cannot be loaded by QualifiedTableSchema — the request is missing required params (name, and optionally schema/catalog) or has values of the wrong type. It surfaces as INVALID_PAYLOAD_SCHEMA_ERROR (422) with the marshmallow messages attached.

Source

Thrown at superset/databases/api.py:1105

                  schema:
                    $ref: "#/components/schemas/TableExtraMetadataResponseSchema"
            401:
              $ref: '#/components/responses/401'
            404:
              $ref: '#/components/responses/404'
            500:
              $ref: '#/components/responses/500'
        """
        self.incr_stats("init", self.table_metadata.__name__)

        database = DatabaseDAO.find_by_id(pk)
        if database is None:
            raise DatabaseNotFoundException("No such database")

        try:
            parameters = QualifiedTableSchema().load(request.args)
        except ValidationError as ex:
            raise InvalidPayloadSchemaError(ex) from ex
        table_name = str(parameters["name"])
        table = Table(table_name, parameters["schema"], parameters["catalog"])
        try:
            security_manager.raise_for_access(database=database, table=table)
        except SupersetSecurityException as ex:
            # instead of raising 403, raise 404 to hide table existence
            raise TableNotFoundException("No such table") from ex
        # `is_odps_partitioned_table` returns (False, []) for non-ODPS backends
        # and handles its own optional-dependency / network / auth failures
        # internally, so any exception escaping here is an unexpected programming
        # error that should propagate rather than be silently swallowed.
        is_partitioned_table, partition_fields = DatabaseDAO.is_odps_partitioned_table(
            database, table_name
        )
        partition = Partition(is_partitioned_table, tuple(partition_fields))
        # Partition info is engine-agnostic at this layer: the generic dispatch
        # passes it to the engine spec, which decides whether to use it. Non-ODPS
        # specs ignore the parameter.

View on GitHub (pinned to f4587218dd)

Solutions

  1. Include all required query parameters per QualifiedTableSchema: name (and schema/catalog when applicable).
  2. Check the response body's invalid-params details — marshmallow lists exactly which attribute failed.
  3. Fetch the current OpenAPI spec at /swagger/v1 and regenerate the client so required params match.

Example fix

# before
GET /api/v1/database/1/table_metadata/my_table/

# after
GET /api/v1/database/1/table_metadata/my_table/?schema=public&catalog=main
Defensive patterns

Strategy: validation

Validate before calling

params = {"name": table_name, "schema": schema, "catalog": catalog}
assert all(isinstance(v, str) and v for v in params.values()), "query params must be non-empty strings"

Try / catch

from marshmallow import ValidationError
from superset.databases.schemas import QualifiedTableSchema
try:
    QualifiedTableSchema().load(params)
except ValidationError as ex:
    raise ValueError(f"bad table params: {ex.messages}")

Prevention

When it happens

Trigger: GET /api/v1/database/<pk>/table_metadata/<table>/ without required query args, or with schema/catalog params that fail schema validation (e.g. non-string values); URL-encoding mistakes that make the query string unparseable.

Common situations: Clients generated from an older OpenAPI spec omitting the catalog parameter introduced for multi-catalog engines; passing schema as part of the path instead of the query string; forgetting that name is required in request.args.

Related errors

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