{"record":{"id":"508dd9f6c471abf5","repo":"apache/superset","slug":"invalid-payload-schema-error","errorCode":"INVALID_PAYLOAD_SCHEMA_ERROR","errorMessage":"An error happened when validating the request","messagePattern":"An error happened when validating the request","errorType":"exception","errorClass":"InvalidPayloadSchemaError","httpStatus":422,"severity":"error","filePath":"superset/databases/api.py","lineNumber":1105,"sourceCode":"                  schema:\n                    $ref: \"#/components/schemas/TableExtraMetadataResponseSchema\"\n            401:\n              $ref: '#/components/responses/401'\n            404:\n              $ref: '#/components/responses/404'\n            500:\n              $ref: '#/components/responses/500'\n        \"\"\"\n        self.incr_stats(\"init\", self.table_metadata.__name__)\n\n        database = DatabaseDAO.find_by_id(pk)\n        if database is None:\n            raise DatabaseNotFoundException(\"No such database\")\n\n        try:\n            parameters = QualifiedTableSchema().load(request.args)\n        except ValidationError as ex:\n            raise InvalidPayloadSchemaError(ex) from ex\n        table_name = str(parameters[\"name\"])\n        table = Table(table_name, parameters[\"schema\"], parameters[\"catalog\"])\n        try:\n            security_manager.raise_for_access(database=database, table=table)\n        except SupersetSecurityException as ex:\n            # instead of raising 403, raise 404 to hide table existence\n            raise TableNotFoundException(\"No such table\") from ex\n        # `is_odps_partitioned_table` returns (False, []) for non-ODPS backends\n        # and handles its own optional-dependency / network / auth failures\n        # internally, so any exception escaping here is an unexpected programming\n        # error that should propagate rather than be silently swallowed.\n        is_partitioned_table, partition_fields = DatabaseDAO.is_odps_partitioned_table(\n            database, table_name\n        )\n        partition = Partition(is_partitioned_table, tuple(partition_fields))\n        # Partition info is engine-agnostic at this layer: the generic dispatch\n        # passes it to the engine spec, which decides whether to use it. Non-ODPS\n        # specs ignore the parameter.","sourceCodeStart":1087,"sourceCodeEnd":1123,"githubUrl":"https://github.com/apache/superset/blob/f4587218dd19d046c3e4d00063e7d27f8a2ed354/superset/databases/api.py#L1087-L1123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Include all required query parameters per QualifiedTableSchema: name (and schema/catalog when applicable).","Check the response body's invalid-params details — marshmallow lists exactly which attribute failed.","Fetch the current OpenAPI spec at /swagger/v1 and regenerate the client so required params match."],"exampleFix":"# before\nGET /api/v1/database/1/table_metadata/my_table/\n\n# after\nGET /api/v1/database/1/table_metadata/my_table/?schema=public&catalog=main","handlingStrategy":"validation","validationCode":"params = {\"name\": table_name, \"schema\": schema, \"catalog\": catalog}\nassert all(isinstance(v, str) and v for v in params.values()), \"query params must be non-empty strings\"","typeGuard":null,"tryCatchPattern":"from marshmallow import ValidationError\nfrom superset.databases.schemas import QualifiedTableSchema\ntry:\n    QualifiedTableSchema().load(params)\nexcept ValidationError as ex:\n    raise ValueError(f\"bad table params: {ex.messages}\")","preventionTips":["Always send name (+ schema/catalog) as query parameters.","Validate against QualifiedTableSchema before the request in tests.","Regenerate clients from the live swagger spec after upgrades."],"tags":["validation","api","table-metadata","query-params"],"backgroundTag":null,"analyzedSha":"f4587218dd19d046c3e4d00063e7d27f8a2ed354","analyzedAt":"2026-08-14T22:39:27.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}