apache/druid · error · IllegalStateException

Failed to update segments with schema information

Error message

Failed to update segments with schema information: %s

What it means

After publishing schemas, SegmentSchemaManager.updateSegmentWithSchemaInformation updates the segments table rows with schema fingerprints; rows that fail to update are collected in failedUpdates. If any update fails, this ISE is thrown so callers do not proceed with segments whose schema linkage is incomplete.

Solutions

Inspect the metadata-store exception logged before this ISE to find the root SQL failure
Retry the operation after transient DB issues — row updates are idempotent per segment
Verify the segment rows still exist in the segments table (they may have been cleaned concurrently)
Check for lock/deadlock contention and DB timeout settings during bulk publish windows

Defensive patterns

Strategy: retry

Validate before calling

// Confirm segment rows exist before updating
segments.forEach(s -> verifyRowExists(segmentsTable, s.getId()));

Try / catch

try {
  manager.persistSchemaAndUpdateSegmentsTable(segments);
} catch (ISE e) {
  retryWithBackoff(() -> manager.persistSchemaAndUpdateSegmentsTable(segments));
}

Prevention

Reduce bulk-update contention by staggering large publishes
Ensure DB deadlock/lock timeout settings accommodate batch updates
Avoid concurrent retention cleanup during schema publish windows

When it happens

Trigger: Calling persistSchemaAndUpdateSegmentsTable when the UPDATE of one or more segment rows in the metadata store fails — DB outage, deadlock/lock timeout, row no longer existing, or connection failure mid-batch.

Common situations: Metadata DB under heavy load during bulk publish; transaction deadlocks with concurrent task updates; segment rows deleted by retention/cleanup racing this update; transient network failures.

Related errors

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/segment/metadata/SegmentSchemaManager.java:332

                          .bind("num_rows", segmentSchema.getSegmentSchemaMetadata().getNumRows())
                          .bind("last_updated", updateTime.toString());
      }

      final int[] affectedRows = segmentUpdateBatch.execute();
      final List<SegmentId> failedUpdates = new ArrayList<>();
      for (int i = 0; i < partition.size(); ++i) {
        if (affectedRows[i] != 1) {
          failedUpdates.add(partition.get(i).getSegmentId());
        }
      }

      if (failedUpdates.isEmpty()) {
        log.infoSegmentIds(
            partition.stream().map(SegmentSchemaMetadataPlus::getSegmentId),
            "Updated segments with schema information in the DB"
        );
      } else {
        throw new ISE(
            "Failed to update segments with schema information: %s",
            failedUpdates
        );
      }
    }
  }

  /**
   * Query the metadata DB to filter the fingerprints that already exist.
   * @return Map from fingerprint to its "used" status
   */
  private Map<String, Boolean> getExistingFingerprints(
      final Handle handle,
      final Set<String> fingerprintsToInsert
  )
  {
    if (fingerprintsToInsert.isEmpty()) {
      return Collections.emptyMap();

View on GitHub (pinned to 9b90983fd2)