What causes "Unknown index version[%s]" in apache/druid?

Check the segment's version file content and compare with versions supported by your Druid build.

apache/druid · error · IllegalStateException

Unknown index version[%s]

Error message

Unknown index version[%s]

What it means

IndexIO.loadIndex dispatches loading to an IndexLoader registered for the segment's index version (read from the version file). This IllegalStateException is thrown when the version string is not one of the known loaders (e.g. not '9:v9' or legacy v8), meaning Druid cannot load a segment written by an unrecognized or unsupported format.

Source

Thrown at processing/src/main/java/org/apache/druid/segment/IndexIO.java:224

      }
    }
  }

  public QueryableIndex loadIndex(File inDir) throws IOException
  {
    return loadIndex(inDir, false, SegmentLazyLoadFailCallback.NOOP);
  }

  public QueryableIndex loadIndex(File inDir, boolean lazy, SegmentLazyLoadFailCallback loadFailed) throws IOException
  {
    final int version = SegmentUtils.getVersionFromDir(inDir);

    final IndexLoader loader = indexLoaders.get(version);

    if (loader != null) {
      return loader.load(inDir, mapper, lazy, loadFailed);
    } else {
      throw new ISE("Unknown index version[%s]", version);
    }
  }

  public static void checkFileSize(File indexFile) throws IOException
  {
    final long fileSize = indexFile.length();
    if (fileSize > Integer.MAX_VALUE) {
      throw new IOE("File[%s] too large[%d]", indexFile, fileSize);
    }
  }

  interface IndexIOHandler
  {
    MMappedIndex mapDir(File inDir) throws IOException;
  }

  private static void validateRowValues(
      RowPointer rp1,

View on GitHub (pinned to 9b90983fd2)

Solutions

Check the segment's version file content and compare with versions supported by your Druid build.
Upgrade Druid to a version that supports the segment's index version (never downgrade below the writer's version).
Re-ingest the data with the current Druid version to produce segments in a supported format.
If the version file is corrupted, restore the segment from a known-good copy in deep storage.

Defensive patterns

Strategy: validation

Validate before calling

// before loadIndex, read the version file and check support
String version = Files.toString(new File(inDir, "version.bin"), StandardCharsets.UTF_8).trim();
if (!version.startsWith("9:")) { // supported by this IndexIO build
  throw new IllegalStateException("Unsupported segment version: " + version);
}

Try / catch

try {
  indexable = indexIO.loadIndex(segmentDir);
} catch (ISE e) {
  if (e.getMessage().startsWith("Unknown index version")) {
    log.error("Segment written by unsupported Druid version: %s", e.getMessage());
    // re-ingest data or upgrade Druid
  }
  throw e;
}

Prevention

Never run a Druid version older than the one that wrote your segments.
Verify the version file after any segment copy from another cluster.
Re-ingest data rather than copying segments across incompatible Druid versions.
Monitor cluster version skew between historicals/overlords before rolling upgrades.

When it happens

Trigger: Loading a segment whose version file contains an unknown version string — segments written by a much newer Druid, corrupted version files, or fabricated index directories.

Common situations: Downgrading Druid below the version that wrote the segments; copying segments from a cluster running a newer Druid; manual segment directory manipulation or deep-storage corruption of the version file.

Related errors

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