After rolled-back segment names are reused, reopening an old NRT reader throws a misleading IllegalStateException

DirectoryReader.openIfChanged(DirectoryReader, IndexCommit) promises a new reader when the commit differs, and Lucene has supported it for near-real-time readers since LUCENE-4898. Keep such a reader open while its writer is rolled back without ever committing, then open a second writer and roll it back as well: the second writer's IndexFileDeleter moves the segment counter past the leftover _0 files and deletes them as unreferenced, and its rollback discards the raised counter. A third writer then names its new segment _0 again, with a new segment id, and commits. Reopening the old reader on that commit looks old segment readers up by name, finds a different id and throws the LUCENE-5931 guard's IllegalStateException, whose message says the application illegally removed index files and advises OpenMode.CREATE, which does not help. No wrong result was observed: the old reader keeps working and a fresh DirectoryReader.open(commit) is correct. From 4.3.0 to 6.1.0 the same call silently returned the stale 1-document reader. A 19-line change that opens such segments fresh for NRT readers passes the repro and the whole core test suite.

// IndexWriter.java:2169-2181 (abridged): names come from an in-memory counter
private final String newSegmentName() {
  synchronized (segmentInfos) {
    // Important to increment changeCount so that the segmentInfos is written on close.  Otherwise we
    // could close, re-open and re-return the same segment name that was previously returned ...
    changeCount.incrementAndGet();
    segmentInfos.changed();
    return "_" + Long.toString(segmentInfos.counter++, Character.MAX_RADIX);
  }
}

// IndexFileDeleter.java:217-233 (writer startup)
inflateGens(segmentInfos, relevantFiles, infoStream);   // :318-327  counter = 1 + max segment name on disk
Set<String> toDelete = fileDeleter.getUnrefedFiles();   // files no commit refers to
fileDeleter.deleteFilesIfNoRef(toDelete);

// StandardDirectoryReader.java:507-511: reopening to a commit passes the old leaves ...
return StandardDirectoryReader.open(directory, infos, getSequentialSubReaders(), subReadersSorter, executorService);
// :249-261 ... which are looked up by segment NAME
previousSegmentReaders.put(sr.getSegmentName(), Integer.valueOf(i));
// :274-283: same name, different id -> blame the application
// Make a best effort to detect when the app illegally "rm -rf" their
// index while a reader was open, and then called openIfChanged:
if (oldReader != null
    && Arrays.equals(commitInfo.info.getId(), oldReader.getSegmentInfo().info.getId()) == false) {
  throw new IllegalStateException("same segment " + commitInfo.info.name + " has invalid doc count change; ...");
}

Without the second writer, w3 itself sees the leftover _0 files, moves its counter to 1 and writes _1: no name collides and the reopen returns the 2-document reader. On a file system that cannot delete open files (the test framework's WindowsFS, a simulation, not a run on Windows), the files stay as pending deletions, which the next writer also counts (IndexFileDeleter.java:211-217), so it does not collide either. With an index that already has a commit, the same sequence collides on the uncommitted _1 instead.

The guard does a real job: before it existed (4.3.0 to 6.1.0), the same call silently reused the stale _0 reader. What is wrong is the decision to throw, with a diagnosis that is false here.

• Who is hit. An application that keeps an NRT reader open across writer sessions in one directory, where two consecutive sessions end in rollback() with no commit in between, and then reopens the old reader with openIfChanged(reader, commit). Lucene's SearcherManager makes this call when built on a writer with a RefreshCommitSupplier that returns a commit (SearcherManager.java:199-200, since 10.3.0; the default supplier returns null, which takes the writer path): after the same sequence maybeRefresh() throws the same exception, while without the second writer it refreshes to 2 documents.
• Configuration. Default IndexWriterConfig, public API, single thread; the plain main() probe (lucene-core only) uses the stock codec. Executed on ByteBuffersDirectory, and on MMapDirectory and NIOFSDirectory on Linux. File systems that refuse to delete open files avoid it (the study's WindowsFS control, a simulation, not a run on Windows).
• How often. Rare: it needs two rolled-back sessions in a row with no commit, while an old NRT reader stays open. As few as 1 old and 2 new documents trigger it. It also happens on an index that already has a commit (the collision is then on the uncommitted _1).
• What goes wrong. The reopen fails with an IllegalStateException that says the application illegally removed index files; its advice (IndexWriter.deleteAll or OpenMode.CREATE) does not apply, and OpenMode.CREATE was run: the same exception. No wrong result was observed: the old reader keeps working and DirectoryReader.open(commit) is correct.
• Why it matters beyond the message. The same name reuse is the trigger for a separate, more serious defect in the same hunt: merge instances re-open segment files by name, so addIndexes of an old leaf can copy another segment's data on main. That one needs its own fix.
• Impact class: wrong error; priority low.

The class sits in org.apache.lucene.index by Lucene test convention but uses nothing package-private.

Control: delete the line new IndexWriter(dir, new IndexWriterConfig()).rollback(); and the test passes on main, so the second rolled-back writer is the trigger.

The same failure through the repro harness: main 645d4fe14a20 with assertions on and off (10 of 10 runs with assertions off), and the 10.5.2 and 9.12.3 release jars with assertions on and off.

# gradle, main 645d4fe14a20, seed DEADBEEF, assertions on (stack abridged)
TestReopenAfterTwoRollbacks > testReopenNrtReaderOnCommitAfterTwoRollbacks FAILED
    java.lang.IllegalStateException: same segment _0 has invalid doc count change; likely you are re-opening a reader after illegally removing index files yourself and building a new index in their place.  Use IndexWriter.deleteAll or open a new IndexWriter using OpenMode.CREATE instead
        at org.apache.lucene.index.StandardDirectoryReader.getOldSegmentReader(StandardDirectoryReader.java:279)
        at org.apache.lucene.index.StandardDirectoryReader.createSegmentReaders(StandardDirectoryReader.java:236)
        at org.apache.lucene.index.StandardDirectoryReader.open(StandardDirectoryReader.java:181)
        at org.apache.lucene.index.StandardDirectoryReader.doOpenIfChanged(StandardDirectoryReader.java:509)
        ...
        at org.apache.lucene.index.StandardDirectoryReader.doOpenFromCommit(StandardDirectoryReader.java:504)
        at org.apache.lucene.index.StandardDirectoryReader.doOpenFromWriter(StandardDirectoryReader.java:459)
        at org.apache.lucene.index.StandardDirectoryReader.doOpenIfChanged(StandardDirectoryReader.java:413)
        at org.apache.lucene.index.DirectoryReader.openIfChanged(DirectoryReader.java:284)
        at org.apache.lucene.index.TestReopenAfterTwoRollbacks.testReopenNrtReaderOnCommitAfterTwoRollbacks(TestReopenAfterTwoRollbacks.java:39)
:lucene:core:test (FAILURE): 1 test, 1  failure

# repro harness, the same exception: main -ea and -da, 10.5.2 -ea and -da, 9.12.3 -ea and -da
# with fix A: the test passes (gradle, with 9 related suites, assertions on and off)

• Contract. DirectoryReader.java:276-281: "If the IndexCommit differs from what the provided reader is searching, open and return a new reader; else, return null." No NRT or closed-writer exception is stated. CHANGES.txt:14052-14054 (LUCENE-4898): "DirectoryReader.openIfChanged now allows opening a reader on an IndexCommit starting from a near-real-time reader (previously this would throw IllegalArgumentException)."
• Upstream tests reopen an NRT reader on a commit: TestDirectoryReaderReopen.testOpenIfChangedNRTToCommit (:649-671) and TestIndexWriterReader.testReopenNRTReaderOnCommit (:1179).
• Old readers keep working across writer sessions. IndexWriter.java:103-108: with OpenMode.CREATE "The old readers will continue to search the "point in time" snapshot they had opened, and won't see the newly created index until they re-open." This documents searching, not reopening an orphaned NRT reader (see the devil's advocate).
• The guard is for application abuse. StandardDirectoryReader.java:274-275; CHANGES.txt:9027-9029 (LUCENE-5931): "Detect when an application tries to reopen an IndexReader after (illegally) removing the old index and reindexing"; CHANGES.txt:12286-12290 (LUCENE-5684): "when IndexReader is reopened after all files in its index were removed and recreated by the application". The guard's test calls its trigger "Abuse" (TestDirectoryReaderReopen.testDeleteIndexFilesWhileReaderStillOpen, :1043-1090). In #6993 rmuir asked "Can you make a test change to trip it without manually removing files from your index?" and mikemccand answered "I don't think so ... the only way I know of this happening is if an app has a reader open, then removes the index, rebuilds it, then tries to openIfChanged the reader". This sequence trips it with no file removed by the application.
• Lucene knows names get reused after its own cleanup. util/FileDeleter.java:176-181: "it's very unusual yet possible ... if you open IW on a crashed index, and it removes a bunch of unref'd files, and then you add new docs / do merging, and it reuses that segment name." IndexWriter.java:2173-2177 bumps the change count so a writer does not "close, re-open and re-return the same segment name".

Strongest case for "works as designed": the NRT note "Once the writer is closed, any outstanding readers may continue to be used. However, if you attempt to reopen any of those readers, you'll hit an AlreadyClosedException" makes reopening an orphaned NRT reader unsupported; the guard is deliberate, results are never wrong and DirectoryReader.open(commit) is an easy workaround; maintainers have said that mixing files from several writers is unsupported (dev@/java-user@ 2022, "customize segment names?"). Two of the study's verifiers and one noise triage leaned this way, and the read-only cross-model reviewer rated this argument "strong".

Why it fails:

1. The note is written on openIfChanged(DirectoryReader, IndexWriter) and its executor variant (DirectoryReader.java:330-332, :372-374) and on the package-private IndexWriter.getReader (:507-509), whose readers' openIfChanged "will simply forward back to this method" (:493). The commit overload has not gone through the writer since LUCENE-4898 (StandardDirectoryReader.java:456-459) and returns the new reader after a rollback in every control; TestIndexWriterReader.testAfterClose asserts the AlreadyClosedException only for openIfChanged(r).
2. Even under the broad reading, the outcome is not the documented one: a different exception with a false diagnosis, and only when a name was reused.
3. A one-file change returns the right reader and keeps the abuse detection the upstream tests assert, so the failure is not a necessary cost of the guard. No files are mixed: the writers run one after another, each holding the write lock.

What stays open: the docs do not say what reopening an NRT reader whose writer was rolled back should do, so this is a gray zone (a later cross-model fact check rated the intended-behaviour case "moderate"). A maintainer could reasonably choose a message or javadoc fix (C) over fix A.

Fix A was run and is recommended; B and C were not run. Workaround for users today: after rolling writers back, open a fresh reader with DirectoryReader.open(commit) instead of openIfChanged(oldNrtReader, commit), or close (commit) the middle writer instead of rolling it back, which saves the counter.

In StandardDirectoryReader.doOpenIfChanged(SegmentInfos, ExecutorService), the path behind openIfChanged(r, commit), drop old leaves whose segment id differs from the same-named segment of the commit when the reader is NRT (writer != null). Those segments are then opened fresh from the files on disk; leaves with matching ids are reused as before. Plain readers still throw the guard's exception. This is a policy choice, not only a better message: for NRT readers the abuse exception on this path goes away.

--- a/lucene/core/src/java/org/apache/lucene/index/StandardDirectoryReader.java
+++ b/lucene/core/src/java/org/apache/lucene/index/StandardDirectoryReader.java
@@ -506,8 +506,26 @@ public final class StandardDirectoryReader extends DirectoryReader {
 
   DirectoryReader doOpenIfChanged(SegmentInfos infos, ExecutorService executorService)
       throws IOException {
+    List<? extends LeafReader> oldReaders = getSequentialSubReaders();
+    if (writer != null) {
+      // An NRT reader may hold segments that were never committed. Once its writer is rolled back,
+      // a later writer can reuse those segment names for different segments, so only reuse an old
+      // segment reader if its segment id matches:
+      Map<String, byte[]> ids = HashMap.newHashMap(infos.size());
+      for (SegmentCommitInfo info : infos) {
+        ids.put(info.info.name, info.info.getId());
+      }
+      List<LeafReader> sameIds = new ArrayList<>(oldReaders.size());
+      for (LeafReader leaf : oldReaders) {
+        SegmentInfo info = ((SegmentReader) leaf).getSegmentInfo().info;
+        if (Arrays.equals(ids.get(info.name), info.getId())) {
+          sameIds.add(leaf);
+        }
+      }
+      oldReaders = sameIds;
+    }
     return StandardDirectoryReader.open(
-        directory, infos, getSequentialSubReaders(), subReadersSorter, executorService);
+        directory, infos, oldReaders, subReadersSorter, executorService);
   }
 
   @Override

Trade-offs

For NRT readers this path no longer reports an application that deleted and rebuilt the index; it returns a correct fresh reader instead (plain readers still throw, as the guard's upstream test asserts). Only openIfChanged(nrtReader, commit) changes; the writer-based reopen and the replicator's direct StandardDirectoryReader.open are untouched. The name reuse itself remains, so the merge-instance defect that it triggers still needs its own fix. Keying on SegmentReader.isNRT instead does not work: a pooled NRT segment reader without deletes has isNRT == false; a variant that passes a flag into getOldSegmentReader was also run green.

What the checks validated

• Scratch worktree of main 645d4fe14a20 (removed afterwards), seed DEADBEEF: stock, the test fails through gradle; with A it passes.
• The repro and 9 related suites with A, -Ptests.asserts=true and false: TestDirectoryReaderReopen (including the guard's own testDeleteIndexFilesWhileReaderStillOpen and testOpenIfChangedNRTToCommit), TestIndexWriterReader (including testAfterClose and testReopenNRTReaderOnCommit), TestDirectoryReader, TestRollback, TestTransactionRollback, TestIndexFileDeleter, TestIndexWriterDelete, TestNRTReaderWithThreads, TestSearcherManager: 143 tests, 7 skipped, 0 failures each time.
• All of :lucene:core:test with A (assertions on): 8,898 tests (gradle's count), 322 skipped, 0 failures. checkGoogleJavaFormat and the forbidden-API checks of :lucene:core pass.
• With A shadowed into the main jars: a plain main() probe returns the 2-document reader on ByteBuffersDirectory, MMapDirectory and NIOFSDirectory, also with OpenMode.CREATE, and SearcherManager.maybeRefresh() with a RefreshCommitSupplier succeeds. The study's two 8-test classes: every bug case passes, including the existing-commit case that collides on _1; the one remaining failure is a test that asserts the stock exception for the OpenMode.CREATE advice, which flips as expected.

Make a writer never re-issue a name whose files its deleter removed at startup: for example, do not delete unreferenced files newer than the last commit (rmuir's proposal in LUCENE-6171 to "only delete files older than the current commit point", never committed), at least until a commit has saved a counter past them; or skip extra names at writer startup (rmuir on #6965: "gobble up extra generations on IW bootup").

Trade-offs

Attacks the root cause and would also cover the merge-instance defect and #6965, but only a completed commit leaves a saved counter, and rollback() must not write one; keeping leftover files changes cleanup behaviour; a counter jump only makes collisions unlikely. Larger and riskier than A. Not run.

Say that a segment name can also be reused after rolled-back writer sessions, and suggest DirectoryReader.open(commit).

Trade-offs

Cheap, but the documented call still fails (the repro test still fails) and the message loses the clear abuse diagnosis it exists for. At most a complement to A. Not run.

• Method: model-based randomized testing (the study's non-formal baseline), 2026-10-22, main 7cecf79523: an executable reference model of writer and reader state, random operation sequences, a conformance check at every reader-producing step and automatic shrinking of failing sequences. First hit in the first run after 161 s (sequence 1,809).
• Re-finds: TLA+ (TLC), Alloy, P, Dafny, OpenJML and JBMC experiments reached the same sequence; all were hinted (the candidate was on their task list), so none is a blind formal discovery.
• Reduction: the study's two 8-test classes (3 of 8 fail in each) were minimized on 2026-10-29 to the one test above, and a control without the second rollback was run.