apache/druid · error · IllegalArgumentException

Table name is required

Error message

Table name is required

What it means

Syntactic validation guard in TableMetadata.validate(): a catalog table object must carry a non-empty identifier in its fully qualified table id, since without a table name the definition cannot be addressed, persisted, or referenced by SQL. It fires when a table definition is submitted (create/update via the catalog API or tests) whose id.name() is null or empty; give the table a name in the schema-qualified identifier. Schema and non-null spec are checked by sibling guards in the same method.

Source

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

  }

  @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)
  {
    if (o == this) {
      return true;
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Provide a non-empty table name in the TableId before validating
2. Fix name parsing/splitting logic so the name segment is captured correctly
3. Validate the identifier string format before constructing TableMetadata

Example fix

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

if (Strings.isNullOrEmpty(id.name())) {
  throw new IllegalArgumentException("table name is required");
}

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

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

When it happens

Trigger: Calling TableMetadata.validate() where id.name() is null or empty — e.g. a TableId built with only a schema, or an ID string like "druid." that parses to an empty name.

Common situations: Incomplete qualified-name parsing ("druid." with trailing dot); programmatic TableId construction missing the name; truncated JSON id objects in API payloads.

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
• Database schema 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/029f26d37a45b4a3. Report an issue: GitHub.