apache/druid · error · CatalogException

CatalogException.validationError(e) (wraps IAE/DruidExceptio

Error message

CatalogException.validationError(e) (wraps IAE/DruidException validation message)

What it means

CatalogResource.postTable validates a new table spec via catalog.validate(table); validation failures surface as IAE or DruidException and are rethrown as CatalogException.validationError(e), which wraps the original validation message. This is the catalog's way of rejecting table specs that violate schema/defn rules during table creation.

Source

Thrown at extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/http/CatalogResource.java:153

      @PathParam("schema") String schemaName,
      @PathParam("name") String tableName,
      TableSpec spec,
      @QueryParam("version") long version,
      @QueryParam("overwrite") boolean overwrite,
      @Context final HttpServletRequest req
  )
  {
    try {
      final SchemaSpec schema = validateSchema(schemaName, true);
      validateTableName(tableName);
      authorizeTable(schema, tableName, ACTIONS_FOR_WRITE, req);
      validateTableSpec(schema, spec);
      final TableMetadata table = TableMetadata.newTable(TableId.of(schemaName, tableName), spec);
      try {
        catalog.validate(table);
      }
      catch (IAE | DruidException e) {
        throw CatalogException.validationError(e);
      }

      long newVersion;
      if (version != 0) {
        // A version is provided. Update that version (only).
        newVersion = catalog.tables().update(table, version);
      } else {
        try {
          // No version. Create the table.
          newVersion = catalog.tables().create(table);
        }
        catch (DuplicateKeyException e) {
          // Table exists
          if (overwrite) {
            // User wants to overwrite, so do so.
            newVersion = catalog.tables().replace(table);
          } else {
            throw e;

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Read the wrapped validation message and fix the offending field in the table spec.
2. Validate the spec offline by calling spec.validate() in a test or CLI before posting.
3. Ensure the spec type is supported by the target schema (accepted via schema.accepts).
4. Compare against a known-good example spec of the same type.

Example fix

// before: spec missing required column definition
// {"type":"avro","columns":[]}
// after
// {"type":"avro","columns":[{"name":"ts","type":"long","sqlType":"BIGINT"}]}

// client-side pre-check
// ensure spec JSON has required fields and a type accepted by the target schema before POSTing

try { catalogResource.postTable(schemaName, tableName, 0, specJson); }
catch (CatalogException e) { if (e.isValidation()) { log.error("Invalid table spec: {}", e.getMessage()); } else { throw e; } }

When it happens

Trigger: POST to the catalog table resource with a table spec that fails spec/schema validation, e.g. invalid column definitions, missing required properties, or a spec type the validator rejects.

Common situations: Hand-written table JSON missing required fields; column specs incompatible with the schema's rules; copy-pasted specs from other schemas; API clients building specs programmatically with wrong types.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• External HTTP tables must provide either a URI or a %s prope
• An external HTTP table with a URI must also provide the corr
• An external HTTP table with a URI must also provide the corr
• An external S3 table with a format must also provide the cor
• Provide either the %s property, or one of the S3 input sourc

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/5d9060a5681a40c2. Report an issue: GitHub.