apache/druid · error · IllegalStateException

Unknown TableState code:

Error message

Unknown TableState code: 

What it means

TableState codes round-trip state through storage as short string codes. fromCode() throws ISE when given a code that matches no TableState enum value — this indicates corrupt or unrecognized persisted state data, since the enum cannot represent it.

Source

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

    TableState(String code)
    {
      this.code = code;
    }

    public String code()
    {
      return code;
    }

    public static TableState fromCode(String code)
    {
      for (TableState state : values()) {
        if (state.code.equals(code)) {
          return state;
        }
      }
      throw new ISE("Unknown TableState code: " + code);
    }
  }

  private final TableId id;
  private final long creationTime;
  private final long updateTime;
  private final TableState state;
  private final TableSpec spec;

  public TableMetadata(
      @JsonProperty("id") TableId tableId,
      @JsonProperty("creationTime") long creationTime,
      @JsonProperty("updateTime") long updateTime,
      @JsonProperty("state") TableState state,
      @JsonProperty("spec") TableSpec spec)
  {
    this.id = tableId;
    this.creationTime = creationTime;

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Fix the stored state code in the metadata store to a valid TableState code
2. Check for version skew: if the metadata was written by a newer Druid, upgrade or revert the row
3. Inspect the code value being passed — it may be null/garbage from a failed deserialization

Example fix

// before
TableState state = TableState.fromCode("ACTIVE"); // not a defined code
// after
TableState state = TableState.fromCode("A"); // use the enum's declared code

boolean knownCode = Arrays.stream(TableState.values()).anyMatch(s -> s.code.equals(code));
if (!knownCode) { /* repair or reject the metadata row */ }

TableState fromCodeOrNull(String code) {
  return Arrays.stream(TableState.values()).filter(s -> s.code.equals(code)).findFirst().orElse(null);
}

try { state = TableState.fromCode(code); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Unknown TableState code")) { state = TableState.defaultState(); /* or quarantine the row */ } else { throw e; } }

When it happens

Trigger: Calling TableState.fromCode(code) with a code string that is not one of the enum's defined codes, typically after deserializing TableMetadata from the metadata store.

Common situations: Manually editing metadata-store rows and writing an invalid state code; metadata written by a newer Druid version with a state code this version's enum lacks (downgrade); data corruption.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Couldn't deserialize authorizer roleMap!
• unknown event type [%s]
• interrupted flushing elements from queue
• Cannot deserialize type[%s] to an RoaringBitmap64Counter:
• Failed to deserialize to RoaringBitmap64Counter, input is an

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