apache/druid · error · IllegalArgumentException

Database schema is required

Error message

Database schema is required

What it means

TableMetadata.validate() performs syntactic checks on a table object. The table's TableId must include a database (Druid) schema segment; a null or empty schema means the table cannot be placed in any schema namespace, so validation fails immediately.

Source

Thrown at server/src/main/java/org/apache/druid/catalog/model/TableMetadata.java:264

  public long updateTime()
  {
    return updateTime;
  }

  @JsonProperty("spec")
  public TableSpec spec()
  {
    return spec;
  }

  /**
   * Syntactic validation of a table object. Validates only that which
   * can be checked from this table object.
   */
  public void validate()
  {
    if (Strings.isNullOrEmpty(id.schema())) {
      throw new IAE("Database schema is required");
    }
    if (Strings.isNullOrEmpty(id.name())) {
      throw new IAE("Table name is required");
    }
    if (spec == null) {
      throw new IAE("A table definition must include a table spec.");
    }
  }

  @Override
  public String toString()
  {
    return CatalogUtils.toString(this);
  }

  @Override
  public boolean equals(Object o)
  {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Build the TableId with a non-empty schema (typically "druid") before validating
2. Include the schema segment when parsing qualified names
3. Check deserialization so the id.schema field is populated from the payload

Example fix

// before
TableMetadata md = new TableMetadata(TableId.of(null, "myTable"), ...);
md.validate();
// after
TableMetadata md = new TableMetadata(TableId.of("druid", "myTable"), ...);
md.validate();

if (Strings.isNullOrEmpty(id.schema())) {
  throw new IllegalArgumentException("set schema before validate()");
}

boolean hasSchema(TableMetadata md) {
  return md.getId() != null && !Strings.isNullOrEmpty(md.getId().schema());
}

try { md.validate(); } catch (IllegalArgumentException e) { if (e.getMessage().equals("Database schema is required")) { /* rebuild TableId with schema */ } else { throw e; } }

When it happens

Trigger: Calling TableMetadata.validate() (directly or on resolution paths) where id.schema() returns null or empty — e.g. a TableId built from just a name, or parsed from a string without a schema qualifier.

Common situations: Parsing a bare table name like "myTable" instead of "druid.myTable"; constructing TableId programmatically without setting schema; JSON payloads omitting the schema field of the ID.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Column name is required
• Table name is required
• Table type is required
• 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/3fed23b8983d5453. Report an issue: GitHub.