{"record":{"id":"6163daf7d59b9aea","repo":"apache/druid","slug":"cannot-start-druid-as-table-s-has-an-incompatibl","errorCode":null,"errorMessage":"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.","messagePattern":"Cannot start Druid as table\\[(.+?)\\] has an incompatible schema\\. Reason: The following columns do not exist in the table: \\[(.+?)\\] See https://druid\\.apache\\.org/docs/latest/operations/upgrade-prep\\.html for more info on remediation\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"server/src/main/java/org/apache/druid/metadata/SQLMetadataConnector.java","lineNumber":1426,"sourceCode":"\n    final boolean schemaPersistenceRequirementMet =\n        !centralizedDatasourceSchemaConfig.isEnabled() ||\n        (tableHasColumn(segmentsTables, \"schema_fingerprint\")\n         && tableHasColumn(segmentsTables, \"num_rows\"));\n\n    StringBuilder missingColumns = new StringBuilder();\n    if (!tableHasColumn(segmentsTables, \"used_status_last_updated\")) {\n      missingColumns.append(\"used_status_last_updated, \");\n    }\n    if (!schemaPersistenceRequirementMet) {\n      missingColumns.append(\"schema_fingerprint, num_rows, \");\n    }\n    if (!tableHasColumn(segmentsTables, \"indexing_state_fingerprint\")) {\n      missingColumns.append(\"indexing_state_fingerprint, \");\n    }\n\n    if (missingColumns.length() > 0) {\n      throw new ISE(\n          \"Cannot start Druid as table[%s] has an incompatible schema.\"\n          + \" Reason: The following columns do not exist in the table: [%s]\"\n          + \" See https://druid.apache.org/docs/latest/operations/upgrade-prep.html for more info on remediation.\",\n          tablesConfigSupplier.get().getSegmentsTable(),\n          missingColumns.substring(0, missingColumns.length() - 2)\n      );\n    } else {\n      // do nothing\n    }\n  }\n\n  private static void throwIfUnchecked(Throwable t)\n  {\n    final Throwable rootCause = Throwables.getRootCause(t);\n    if (rootCause instanceof DruidException druidException) {\n      throw druidException;\n    }\n    Throwables.throwIfUnchecked(t);","sourceCodeStart":1408,"sourceCodeEnd":1444,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/metadata/SQLMetadataConnector.java#L1408-L1444","documentation":"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.","triggerScenarios":"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.","commonSituations":"Version upgrades skipping release notes; metadata store shared between old and new clusters; custom segments-table schema that dropped columns.","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."],"exampleFix":"// before\n-- start Druid against old schema\n// after\nALTER TABLE druid_segments ADD COLUMN indexing_state_fingerprint VARCHAR(255);\n-- then start Druid","handlingStrategy":"validation","validationCode":"// run before startup\ncolumns = describeTable(\"druid_segments\");\nfor (String required : [\"indexing_state_fingerprint\", ...]) {\n  if (!columns.contains(required)) {\n    throw new IllegalStateException(\"Missing column \" + required + \"; run schema upgrade\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  connector.startMetastoreChecks(); // implicit at startup\n} catch (IllegalStateException e) {\n  log.error(e, \"Metadata schema incompatible; apply upgrade scripts\");\n  System.exit(1);\n}","preventionTips":["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"],"tags":["metadata","schema","upgrade","startup"],"backgroundTag":"schema-validation-failed","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}