apache/druid · critical · IllegalStateException

Cannot start Druid as table

Error message

Cannot start Druid as table[%s] has an incompatible schema. Reason: The following columns do not exist in the table: [%s] See https://druid.apache.org/docs/latest/operations/upgrade-prep.html for more info on remediation.

What it means

SQLMetadataConnector performs a startup schema-compatibility check on the segments table. If required columns (such as indexing_state_fingerprint) are missing, it refuses to start and throws IllegalStateException pointing to the upgrade-prep documentation. This protects against running a newer Druid against an old, un-migrated metadata schema.

Solutions

Run the metadata-store upgrade SQL scripts from the Druid version you're deploying (see the upgrade-prep guide linked in the message).
Back up the metadata DB, then ALTER TABLE druid_segments ADD COLUMN the listed missing columns with correct types.
Verify the metadata.initializationScripts / schema version matches the running Druid version.
If the table was customized, restore the standard schema columns.

Example fix

// before
-- start Druid against old schema
// after
ALTER TABLE druid_segments ADD COLUMN indexing_state_fingerprint VARCHAR(255);
-- then start Druid

Defensive patterns

Strategy: validation

Validate before calling

// run before startup
columns = describeTable("druid_segments");
for (String required : ["indexing_state_fingerprint", ...]) {
  if (!columns.contains(required)) {
    throw new IllegalStateException("Missing column " + required + "; run schema upgrade");
  }
}

Try / catch

try {
  connector.startMetastoreChecks(); // implicit at startup
} catch (IllegalStateException e) {
  log.error(e, "Metadata schema incompatible; apply upgrade scripts");
  System.exit(1);
}

Prevention

Follow the upgrade-prep guide for every Druid version bump
Test schema migrations against a DB copy before production
Keep the metadata schema version aligned with the Druid version
Do not drop columns from druid_segments in custom setups

When it happens

Trigger: Starting Coordinator/Overlord after upgrading Druid without running the metadata-store schema migration that adds new columns to druid_segments; pointing Druid at a legacy metadata DB created by an older version.

Common situations: Version upgrades skipping release notes; metadata store shared between old and new clusters; custom segments-table schema that dropped columns.

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

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/metadata/SQLMetadataConnector.java:1426

    final boolean schemaPersistenceRequirementMet =
        !centralizedDatasourceSchemaConfig.isEnabled() ||
        (tableHasColumn(segmentsTables, "schema_fingerprint")
         && tableHasColumn(segmentsTables, "num_rows"));

    StringBuilder missingColumns = new StringBuilder();
    if (!tableHasColumn(segmentsTables, "used_status_last_updated")) {
      missingColumns.append("used_status_last_updated, ");
    }
    if (!schemaPersistenceRequirementMet) {
      missingColumns.append("schema_fingerprint, num_rows, ");
    }
    if (!tableHasColumn(segmentsTables, "indexing_state_fingerprint")) {
      missingColumns.append("indexing_state_fingerprint, ");
    }

    if (missingColumns.length() > 0) {
      throw new ISE(
          "Cannot start Druid as table[%s] has an incompatible schema."
          + " Reason: The following columns do not exist in the table: [%s]"
          + " See https://druid.apache.org/docs/latest/operations/upgrade-prep.html for more info on remediation.",
          tablesConfigSupplier.get().getSegmentsTable(),
          missingColumns.substring(0, missingColumns.length() - 2)
      );
    } else {
      // do nothing
    }
  }

  private static void throwIfUnchecked(Throwable t)
  {
    final Throwable rootCause = Throwables.getRootCause(t);
    if (rootCause instanceof DruidException druidException) {
      throw druidException;
    }
    Throwables.throwIfUnchecked(t);

View on GitHub (pinned to 9b90983fd2)