The default codec's 'Summary of File Extensions' table (codecs/lucene104 package documentation) is stale: it omits .fdm, .tvm, .tmd, .psm, .dvs, .dvp and .vemf, which the default codec writes, credits .veq to the default HNSW vectors format (which does not write it) and gives 'vex' without its dot; Lucene104PostingsFormat's 'Files and detailed format' list also omits .tmd and .psm (documentation defect; the code is correct)

Finding LFV-972Area: codecs / default codec file-format overview (codecs/lucene104 package-info 'Summary of File Extensions' table and the Lucene104PostingsFormat 'Files and detailed format' list vs the files the default codec writes)Priority: lowImpact: minorNovelty: new

Finding page for LFV-972

AI-assisted finding, confirmed by automated checks, not yet triaged by a human Lucene committer. This site files nothing upstream.

What it shows

You index ordinary documents with the default codec and look up the files in the index directory in the 'Summary of File Extensions' table of the codec's package documentation, which says it 'summarizes the names and extensions of the files' of this format version. Seven extensions the default codec writes are missing (.fdm, .tvm, .tmd, .psm, .dvs, .dvp, .vemf); the vector row lists '.vec, .vem, .veq, vex', but the default Lucene99HnswVectorsFormat it links writes .vec, .vemf, .vem and .vex (.veq comes only from the optional scalar-quantized formats) and 'vex' lacks its dot; and Lucene104PostingsFormat's own 'Files and detailed format' list leaves out .tmd and .psm. Lucene itself reads and writes all these files correctly; each format change since 8.5.0 that added a file updated at most its own class javadoc, never this overview.

The test shows that the default codec (Lucene104) writes .dvp, .dvs, .fdm, .psm, .tmd, .tvm and .vemf files that the "Summary of File Extensions" table of codecs/lucene104/package-info.java does not list (a documentation defect; the code is correct).

Expected vs actual

Expected: every extension written for one ordinary document is in the table. Actual: written extensions missing from the extensions table expected:<[]> but was:<[dvp, dvs, fdm, psm, tmd, tvm, vemf]> (-ea and -da).

Files

Run it

# Lucene checkout at the tested commit, built with: ./gradlew --no-daemon assemble   (JDK 25)
LUCENE=/path/to/lucene; V=12.0.0-SNAPSHOT
CP=$LUCENE/lucene/core/build/libs/lucene-core-$V.jar
CP=$CP:$LUCENE/lucene/codecs/build/libs/lucene-codecs-$V.jar
CP=$CP:$LUCENE/lucene/test-framework/build/libs/lucene-test-framework-$V.jar
CP=$CP:randomizedtesting-runner-2.9.2.jar:junit-4.13.2.jar:hamcrest-3.0.jar   # test-framework dependencies (Maven Central)
CP=$CP:junit-platform-console-standalone-6.1.3.jar   # JUnit Platform console launcher (Maven Central)

javac -d classes -cp "$CP" $(find src -name '*.java')

# run 1: assertions on, seed DEADBEEF
java -ea -esa --add-modules jdk.incubator.vector --enable-native-access=ALL-UNNAMED -Dtests.seed=DEADBEEF \
     -cp "classes:$CP" org.junit.platform.console.ConsoleLauncher \
     execute --select-class org.apache.lucene.codecs.lucene104.TestLucene104ExtensionTable

Gradle alternative: copy the test into the matching module's src/test/ tree of the checkout and run ./gradlew -p lucene/<module> test --tests <class> -Ptests.seed=<seed> (add -Ptests.asserts=false for a run without assertions).

Formal models and scripts this finding's part of the hunt used: codec-format-javadoc-grammar-overflow-liv-cfe-extension-table

Feedback

Open an issue in lucene-ai-bug-hunt. Please do not open issues or pull requests in apache/lucene about this finding unless a Lucene committer agrees it should be filed.

Snapshot of 2026-11-04. AI-assisted; not yet triaged by a human Lucene committer. Feedback: open an issue in lucene-ai-bug-hunt.