A failed addIndexes(CodecReader...) leaves the incoming fields registered in the writer's field schema, so later valid documents that use those names differently are rejected until the writer is reopened

IndexWriter keeps one in-memory registry of field names and their schemas, built from the segments when it opens, and checks every new document against it. addIndexes(CodecReader...) first checks the incoming fields without changing that registry, then merges the readers into a new segment. The merge is built over the writer's own registry, and its first step registers the incoming fields. When a later step of the merge fails (for example a full disk), the call throws and publishes nothing, but nothing removes the registrations. No document is added, as the javadoc promises, but for the rest of the writer session the incoming names keep the incoming schema: a later document that uses such a name differently is rejected with IllegalArgumentException, and getFieldNames() lists the name. With an index sort, incoming document blocks without a parent field, or a one-merge-per-reader merge policy, a rejected import of two conflicting indexes leaves the same residue without any I/O error. Reopening the writer, rollback() or deleteAll() clears it; the index on disk is not damaged. Every release from 4.2.0 through 10.6.0 and main is affected. Merging with private field numbers and registering the fields only when the merged segment is published fixes every executed trigger.

1. The registry (FieldInfos.FieldNumbers) is built when the writer opens (IndexWriter.java:1124).
2. addIndexes(CodecReader...) (:3275) runs "Best effort up front validations": globalFieldNumberMap.verifyFieldInfo(fi) for every incoming field (:3288-3293). verifyFieldInfo only checks (FieldInfos.java:401-408), so a conflict found here leaves nothing behind.
3. The merge runs in addIndexesReaderMerge (IndexWriter.java:3491), whose SegmentMerger is given globalFieldNumberMap, the writer's registry itself (:3568-3577).
4. SegmentMerger.merge() calls mergeFieldInfos() first (SegmentMerger.java:121; the builder over the registry at :75), which adds the incoming FieldInfos one by one (:232-239; a conflict stops the loop) through FieldInfos.Builder.add -> FieldNumbers.addOrGet (FieldInfos.java:788, :415): each new name is registered with its incoming schema. Stored fields, norms, postings, doc values, points, vectors and the .fnm are written after that (SegmentMerger.java:123 on), then the compound file and the .si (IndexWriter.java:3620-3641).
5. When one of those steps fails, the exception reaches the caller: with SerialMergeScheduler straight out of mergeScheduler.merge (IndexWriter.java:3312), with ConcurrentMergeScheduler rethrown at :3376-3384. The finally (:3316-3324) deletes files only of merges whose merge info is set, which happens after merger.merge() returns (:3600); for a failure inside the merge it deletes nothing, and files already written stay unreferenced until the writer is closed or rolled back. Only an Error is tragic (:3390-3393), so the writer stays open. FieldNumbers has no removal except clear() (FieldInfos.java:694-698), which only deleteAll() calls (IndexWriter.java:2800).
6. A later document reaches FieldNumbers.addOrGet -> verifySameSchema (FieldInfos.java:422) and is rejected against the leftover schema; getFieldNames() (IndexWriter.java:2135-2137) lists the name.

Unless the writer has an index sort, or at least one reader of the merge has document blocks and at least one (possibly another) has no parent field (IndexWriter.java:3549-3556), addIndexesReaderMerge first wraps the readers of one merge with SlowCompositeCodecReaderWrapper.wrap (:3560-3566), which merges their FieldInfos in a private FieldNumbers (FieldInfos.java:196-218) and throws on a conflict before anything is registered. With an index sort, in that blocks case (the wrap is skipped), or with a merge policy whose findMerges(CodecReader...) returns one merge per reader (allowed by the javadoc, IndexWriter.java:3264-3267), step 4 registers one reader's f and throws IllegalArgumentException on the other's (within one merge the first reader's; with one merge per reader under the default concurrent scheduler, whichever merge registers first). The rejected call leaves that schema behind: a later document, and even importing the other index alone, is rejected (executed with the first reader's f left behind: addIndexes(c2) is rejected), while a fresh writer accepts c2. The wrap came with #12622 (9.9.0) and the blocks skip with #13128 (9.11.0), so before 9.9.0 a conflicting two-reader import left the residue with the default configuration too.

• Who is hit. Applications that keep using an IndexWriter after addIndexes(CodecReader...) failed. Two ways in: an I/O error once the merge has started (any configuration; the javadoc's own "disk full" example), or a rejected import of indexes that disagree on a field's schema on an index-sorted writer, with incoming document blocks without a parent field, or with a merge policy that returns one merge per reader (and with the default configuration on every release before 9.9.0).
• What they see. Every later document that gives an incoming name another schema fails with IllegalArgumentException; getFieldNames() lists the name. After the conflict trigger, importing only the second index is rejected too.
• Loud, no data damage. Nothing of the failed import is added or committed, no commit references its files, and documents that do not use those names are accepted as usual. After an I/O error, a retry of the same import works (it has the same schema). Files a failed merge already wrote stay in the directory, unreferenced, until the writer is closed or rolled back; they are harmless and not part of this bug.
• How long. Until the writer is reopened, rolled back or deleteAll() is called.
• Default configuration. The I/O trigger needs no setting: a default-configuration check with ConcurrentMergeScheduler shows the same residue; the repro uses SerialMergeScheduler to keep the merge and its exception on the test thread.
• Likelihood. Contrived (rare in practice): accidental harm needs an application that abandons the import, keeps the same writer without rollback() or a reopen, and then indexes an incoming name differently.
• Workaround. Reopen or roll back the writer after a failed addIndexes(CodecReader...).

One test class, one method, single thread, deterministic. Public API plus the test framework's MockDirectoryWrapper.Failure, the upstream idiom for a full disk; SerialMergeScheduler keeps the merge and its exception on the test thread (with the default ConcurrentMergeScheduler, addIndexes throws the same exception, the merge thread reports it as well, and the residue is the same). It asserts only the user-visible harm, the rejected document; the fault-free conflict trigger and the getFieldNames() symptom are left out on purpose. The file is formatted with the project's google-java-format. The suggested regression test is this same test; it fits into TestAddIndexes.java.

The same test fails on the released 10.6.0, 10.5.2 and 9.12.3 jars, and with 30 random seeds on main.

cp $REPRO/TestFailedAddIndexesCodecReaderSchema.java $LUCENE/lucene/core/src/test/org/apache/lucene/index/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.index.TestFailedAddIndexesCodecReaderSchema -Ptests.seed=DEADBEEF
# the same failure with -Ptests.asserts=false

TestFailedAddIndexesCodecReaderSchema > testFailedAddIndexesDoesNotDefineIncomingField FAILED
    java.lang.IllegalArgumentException: cannot change field "f" from index options=DOCS to inconsistent index options=NONE
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:FDDE072C10F6F8B3]:0)
        at org.apache.lucene.index.FieldInfo.verifySameIndexOptions(FieldInfo.java:279)
        at org.apache.lucene.index.FieldInfos$FieldNumbers.verifySameSchema(FieldInfos.java:515)
        at org.apache.lucene.index.FieldInfos$FieldNumbers.addOrGet(FieldInfos.java:422)
        at org.apache.lucene.index.FieldInfos$Builder.add(FieldInfos.java:788)
        at org.apache.lucene.index.FieldInfos$Builder.add(FieldInfos.java:746)
        at org.apache.lucene.index.IndexingChain.initializeFieldInfo(IndexingChain.java:1393)
        ...
        at org.apache.lucene.index.IndexWriter.addDocument(IndexWriter.java:1492)
        at org.apache.lucene.index.TestFailedAddIndexesCodecReaderSchema.testFailedAddIndexesDoesNotDefineIncomingField(TestFailedAddIndexesCodecReaderSchema.java:59)

# main 5adff78bb168, gradle, seed DEADBEEF: the same with -Ptests.asserts=true and =false
# with the recommended fix: BUILD SUCCESSFUL, 1 test, 0 failures, assertions on and off

• Contract. addIndexes(CodecReader...) refers to the addIndexes javadoc "for details on transactional semantics" (IndexWriter.java:3259): "This method is transactional in how Exceptions are handled: it does not commit a new segments_N file until all indexes are added. This means if an Exception occurs (for example disk full), then either no indexes will have been added or they all will have been" (:3084-3086). After the disk-full failure, the incoming index still decides which documents the writer accepts. And getFieldNames() is documented as "all field names as visible from this IndexWriter, across all segments of the index" (:2130-2131); after the failed call it lists f, which no segment, flushed or in memory, holds.
• The overload avoids it on purpose for validation failures. The commit that added the up-front check, 698f40ad51af (LUCENE-10216, #633), lists "verify field info schemas upfront from incoming readers", "Keep addIndexes API transactional" and "Maintain transactionality - register segments with iw after all merges complete". Segment registration was deferred until the merges complete; field registration was not, so failures found up front leave no residue and failures in the merge do.
• Schema definition. lucene/MIGRATE.md:1586-1593: "The per field data-structures are implicitly defined by the first document indexed that contains a certain field." No document with f reached this writer, and a reopened writer on the same files accepts the document.
• Precedent. lucene/CHANGES.txt:21400-21408 (LUCENE-702) made addIndexes(*) transactional and fixed other paths "to clean up and keep the instance state consistent to what's actually in the index"; :20905-20910 (LUCENE-846) fixed a failed addIndexes that could "corrupt the instance of IndexWriter (but, not the index itself)".
• Tests. Upstream's transactional tests check documents and files only; TestIndexWriterOnDiskFull rolls the writer back after a failed attempt (TestIndexWriterOnDiskFull.java:383-392), and we found no upstream test that adds a document to the writer after a failed addIndexes(CodecReader...).

The strongest case for "accepted behaviour": the javadoc sentence is literally about segments_N and the documents added, and that part holds. The registry only grows within a session by design: field infos are "(almost) append-only" (#9597), and in #13369 (the fix of #13353, failed documents) delaying or reverting the registration was tried and not adopted. On #9738 (LUCENE-8692, 2019) a maintainer (s1monw) listed addIndexes() among the methods whose exceptions "might cause documents go missing etc. but we treated them not as fatal or tragic events since a user could always call rollback()". Upstream's disk-full test rolls back, and getFieldNames is @lucene.experimental (IndexWriter.java:2129-2134).

Why it fails: no javadoc, test or discussion says a failed addIndexes may define a field's schema. In #13353 a document with the field did reach the indexing chain; here none did. rollback() discards all uncommitted work, a heavy remedy for a call that promises all or nothing, and the fix is local to addIndexes, where #633 already defers segment registration. Our reading: a defect (the devil's advocate stayed at "uncertain", not "not real"). The usual counter, "call rollback()", is met by the javadoc, #633 and the validation-versus-merge difference. No javadoc promises to undo in-memory bookkeeping (this is an inconsistency in the writer's session state: a call that adds nothing still changes which documents the writer accepts), and the claim is not that every failed call must undo its schema changes.

Three options. Only the first, recommended one covers both triggers and was validated with gradle; the second is a partial fix and the third a documentation change.

In addIndexesReaderMerge, give the SegmentMerger a merge-private FieldNumbers(config.getSoftDeletesField(), config.getParentField()) instead of globalFieldNumberMap (IndexWriter.java:3574) and keep the merge's MergeState.mergeFieldInfos. In addIndexes(CodecReader...), inside the existing synchronized (this) publication block and under synchronized (globalFieldNumberMap), check every merge's fields against the writer (verifyFieldInfo) and against each other (a scratch FieldNumbers), then reserveDocs, then addOrGet them all, before segmentInfos.addAll(infos) (:3366). When a merge fails, drop the kept FieldInfos. One file, 35 insertions and 4 deletions. The core of it:

// addIndexesReaderMerge: number the merged fields privately
new SegmentMerger(readers, segInfo, infoStream, trackingDir,
    new FieldNumbers(config.getSoftDeletesField(), config.getParentField()), ...);

// addIndexes(CodecReader...), in synchronized (this), before segmentInfos.addAll(infos)
synchronized (globalFieldNumberMap) {
  FieldNumbers check = new FieldNumbers(config.getSoftDeletesField(), config.getParentField());
  for (FieldInfos fis : incoming)
    for (FieldInfo fi : fis) { globalFieldNumberMap.verifyFieldInfo(fi); check.addOrGet(fi); }
  reserveDocs(totalDocs);
  for (FieldInfos fis : incoming)
    for (FieldInfo fi : fis) globalFieldNumberMap.addOrGet(fi);
}

Trade-offs

• The new segment's field numbers can differ from the writer's, as segments copied by addIndexes(Directory...) already can.
• A concurrent document that introduces an incoming name with another schema while the merge runs is now accepted, and the addIndexes call then fails at publication with its files deleted (all or nothing); today that document is rejected.
• The cross-check is needed: registering merge by merge still leaves the first merge's fields when a per-reader merge policy splits a conflicting import (executed with an earlier variant of this fix).
• Open #16571 changes SegmentMerger.cleanupMerge and adds a partitioned-merge guard to addIndexes(CodecReader...) right after findMerges; it leaves mergeFieldInfos alone, but whichever lands second may need a small rebase in IndexWriter.java.
• As a prototype, the diff drops the kept FieldInfos after the ensureOpen() at publication; a final patch should drop them first, so a writer closed in between keeps nothing.

What the checks validated

In a scratch worktree at 5adff78bb168, through gradle, seed DEADBEEF: the repro fails without the fix and passes with it, assertions on and off; the two-block conflict check fails without it and passes with it; with the fix TestAddIndexes, TestIndexWriterOnDiskFull, TestIndexSorting, TestDocValuesIndexing, TestIndexOptions, TestIndexWriterExceptions, TestFieldInfos and TestIndexWriterDelete pass (226 tests, 0 failures, 9 skipped), every lucene/core test passes (752 classes, 8,923 tests, 0 failures, 322 skipped; the two-block check ran separately) and checkGoogleJavaFormat is clean. Earlier, on main e1faeba08bde, the index-sorted and per-reader legs were clean with this fix, and a single-fault enumeration over every file creation and write of one call had 0 violations with the same deferred registration.

Extend the up-front check (IndexWriter.java:3288-3293) to also add every reader's fields to a scratch FieldNumbers, so readers that disagree with each other are rejected before the merge.

Trade-offs

Fixes only the fault-free conflict trigger; an I/O error during the merge still leaves the residue.

State in the javadoc that after a failed addIndexes(CodecReader...) the writer's field schema may contain the incoming fields.

Trade-offs

Contradicts the transactional javadoc and the purpose of the up-front check; rollback() also discards all other uncommitted work.

Method: non-formal, then semi-formal.

• Code reading of the addIndexes(CodecReader...) merge and its failure path, and hand-written probes on the stock jar: a simulated disk full while the merged segment is written, and a FilterCodecReader whose stored-fields reader throws during the merge. Both left the incoming name registered and a later document rejected; a reopened writer accepted it.
• A bounded-exhaustive single-fault enumeration on the stock jar: one IOException at every destination createOutput and every IndexOutput write of one call, with SerialMergeScheduler and with ConcurrentMergeScheduler, against the javadoc's all-or-none promise (after a failed call that added no document, getFieldNames() is unchanged and every incoming-only name accepts a document with another schema). It found violations in 14,802 of 14,802 runs, in every merge phase after the field-info step (stored fields, norms, terms, doc values, points, vectors, .fnm, compound file, .si); a no-fault control registers and rejects (the oracle is not vacuous) and a validation-time failure leaves nothing. With the deferred registration the enumeration found 0 violations in 14,786 runs.
• A later code reading of addIndexesReaderMerge found the fault-free trigger (the SlowCompositeCodecReaderWrapper.wrap skip for index sorts and blocks, and per-reader merges), executed with probes on main and on releases back to 8.11.4, and reduced to a one-test check.