A Solr 9 upgrade rarely breaks on a feature you use. It breaks on a default you never set. These are the ones that change behaviour under an unchanged configuration.
A Solr 9 upgrade rarely fails on a feature you use. It fails on a default you never set and never thought about. These are the ones that generate support tickets.
The most common Solr 9 boot failure, and the one-word fix. Full walkthrough in the FastLRUCache error page.
| Setting | Solr 8 | Solr 9 | Why it matters |
|---|---|---|---|
| Cache class | solr.FastLRUCache and friends | CaffeineCache only | Naming a removed class stops the core from loading at all |
| hl.method | original | unified | Highlight output and the parameters that affect it both change. storeOffsetsWithPositions is enough, term vectors are an expensive way to get the same result |
| maxBooleanClauses | 1024, checked at the top level | Enforced recursively | Wide edismax queries with synonym expansion that passed on Solr 8 can now trip the limit |
| blockUnknown | false | true | Basic auth and JWT now reject unauthenticated requests by default. Backwards incompatible on purpose |
| Network binding | All interfaces | localhost | A fresh Solr 9 is not reachable from outside the machine until you say so. Embedded ZooKeeper is the same |
| Java security manager | Off | On | Custom plugins that touch the filesystem or the network may need a policy change |
| Atomic updates on child docs | Fell back on the route parameter | Requires the root field | Partial updates to nested documents fail silently differently than before |
| schemaVersion (from 9.7) | 1.6 | 1.7, docValues on by default | Most types that support docValues get them, and fields become uninvertible=false. Moving to 1.7 generally means a full reindex |
| lib directives (from 9.8) | Always honoured | Opt-in, deprecated | A lib tag is now ignored with a warning unless explicitly enabled, and goes away entirely in Solr 10 |
The docValues trap on text fields
docValues="true" on a solr.TextField is invalid and the core will not start: that field type does not support doc values. If you need to sort or facet on the text, copy it into a string field, or switch the type to solr.SortableTextField. Solr 9.7 turning docValues on by default makes this much easier to hit by accident.
You cannot add docValues without reindexing
Solr 8 let you retrofit doc values with UninvertDocValuesMergePolicy. Lucene 9 closed that door. Adding docValues to an existing field now means a full reindex, every time.
Reindex after any major upgrade
The Solr project recommends a complete reindex after every major version step, not just when the schema changes. Read Solr Best Practices before you plan it, and JVM tuning before you size it.
Solr 9
Defaults that changed in Solr 9 (this page)