apache/druid · error · RE

Unknown version

Error message

Unknown version

What it means

NestedDataColumnSupplier.read() reads the column's version byte and supports only the known versions (e.g. V1-V4). Any other version byte yields RE 'Unknown version <n>'. This typically means the segment was written by a newer Druid than the one reading it, or the file is corrupt.

Source

Thrown at processing/src/main/java/org/apache/druid/segment/nested/NestedDataColumnSupplier.java:194

            fieldInfo,
            compressedRawColumnSupplier,
            nullValues,
            stringDictionarySupplier,
            longDictionarySupplier,
            doubleDictionarySupplier,
            arrayDictionarySupplier,
            columnConfig,
            mapper,
            formatSpec,
            byteOrder,
            logicalType
        );
      }
      catch (IOException ex) {
        throw new RE(ex, "Failed to deserialize V%s column.", version);
      }
    } else {
      throw new RE("Unknown version " + version);
    }
  }


  /**
   * Detects if field dictionary contains any invalid entries from a bug which previously existed in
   * {@link NestedPathFinder#toNormalizedJsonPath(List)} to generate invalid path expressions when faced with empty
   * field names - for example {"":{"a":1}} would incorrectly store the path as $..a instead of $[''].a.
   * <p>
   * If this method detects any illegal paths, the field dictionary is wrapped using {@link FieldsFixupIndexed}, which
   * replaces the invalid values with corrected values, using {@link NestedPathFinder#parseBadJsonPath(String)} and
   * feeding that back into the now fixed {@link NestedPathFinder#toNormalizedJsonPath(List)}.
   * <p>
   * Columns written after the bug was fixed will store {@link NestedCommonFormatColumnPartSerde#pathParserVersion} as
   * 0x01 or greater, to indicate that we do not need to call this method to check for fixing up paths.
   * <p>
   * see https://github.com/apache/druid/pull/19072 for additional details.
   */

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Upgrade Druid to at least the version that wrote the segment (check segment 'version' metadata in segments table).
  2. Re-ingest the data with the current Druid version to produce a compatible column.
  3. Restore the correct segment from deep storage if cache corruption is suspected.
  4. Avoid downgrading a cluster that has already written segments in a newer column format.

Example fix

// before: reader older than writer
// RE: Unknown version 5
// after: upgrade all Druid services to the writer's version, or re-ingest with: 
// "granularitySpec": ... // re-run ingestion on supported version
Defensive patterns

Strategy: type-guard

Validate before calling

// peek the version byte before opening the supplier
data.mark(); byte version = data.get(); data.reset();
if (version != SUPPORTED_VERSION) { /* route to matching supplier or fail fast */ }

Type guard

boolean isKnownVersion(byte v) { return v == 1 || v == 2 || v == 3 || v == 4; }

Try / catch

try {
  col = supplier.get();
} catch (RE e) {
  if (e.getMessage().startsWith("Unknown version")) {
    throw new SegmentIncompatibleException(e, "Upgrade Druid to read this segment");
  } throw e;
}

Prevention

When it happens

Trigger: Opening a nested column whose first version byte is not one of the recognized NestedDataColumnSupplier versions; corrupted column header bytes.

Common situations: Downgraded Druid cluster reading segments written by a newer release; segments produced by a fork/patched build; corrupted cache files.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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