apache/druid · critical · IllegalStateException

announceHistoricalSegments failed with null metadata, should

Error message

announceHistoricalSegments failed with null metadata, should not happen.

What it means

IndexerSQLMetadataStorageCoordinator.commitSegments calls announceHistoricalSegments with null metadata, performing no metadata transaction. The code asserts the result must always succeed in this mode; if it doesn't, an internal invariant is broken and ISE is thrown with this message.

Source

Thrown at server/src/main/java/org/apache/druid/metadata/IndexerSQLMetadataStorageCoordinator.java:440

  @Override
  public Set<DataSegment> commitSegments(
      final Set<DataSegment> segments,
      @Nullable final SegmentSchemaMapping segmentSchemaMapping
  )
  {
    final SegmentPublishResult result =
        commitSegmentsAndMetadata(
            segments,
            null,
            null,
            null,
            segmentSchemaMapping
        );

    // Metadata transaction cannot fail because we are not trying to do one.
    if (!result.isSuccess()) {
      throw new ISE("announceHistoricalSegments failed with null metadata, should not happen.");
    }

    return result.getSegments();
  }

  @Override
  public SegmentPublishResult commitSegmentsAndMetadata(
      final Set<DataSegment> segments,
      @Nullable final String supervisorId,
      @Nullable final DataSourceMetadata startMetadata,
      @Nullable final DataSourceMetadata endMetadata,
      @Nullable final SegmentSchemaMapping segmentSchemaMapping
  )
  {
    verifySegmentsToCommit(segments);
    IndexerMetadataStorageCoordinator.validateDataSourceMetadata(supervisorId, startMetadata, endMetadata);
    final String dataSource = segments.iterator().next().getDataSource();

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Check metadata-store connectivity and the coordinator logs for the underlying SQL failure
2. Retry the segment commit — the operation is designed to be retried on transient DB failures
3. Resolve duplicate/racing segment announcements; verify no two tasks are publishing overlapping segments

Example fix

// before
coordinator.commitSegments(segments, null, segmentSchemaMapping); // no retry
// after
RetryUtils.retry(() -> coordinator.commitSegments(segments, null, segmentSchemaMapping), RetryUtils.IS_RETRYABLE, 3);

try { return coordinator.commitSegments(segments, null, segmentSchemaMapping); } catch (IllegalStateException e) { if (e.getMessage().contains("announceHistoricalSegments failed")) { // transient metadata-store issue; retry with backoff throw new RetryableException(e); } throw e; }

When it happens

Trigger: commitSegments when the underlying announceHistoricalSegments transaction fails despite metadata being null — e.g. database connectivity failure, SQL error inserting segments, or a race losing a segment-insert conflict during the segment announcement.

Common situations: Metadata DB outage or lock contention during segment publish; duplicate segment announcement races between tasks; schema mismatches after Druid upgrades.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• null/empty intervals
• Unhandled type: %s
• Column is not multi-valued
• Not a numeric value type:
• Size[%d] > expansion.length[%d] or < 0

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