You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Search analyzer fingerprint pins index to exact ICU patch version; mismatch error suggests a dangerous rebuild #75
The search analyzer fingerprint (packages/search-analysis — analyzer.js builds it from process.versions.icu) pins the index to the exact ICU patch version of the Node process that wrote it. Any client on a different Node patch release is then locked out of writing to the index — even when the ICU difference almost certainly has no effect on tokenization.
What happened
Running import-docs.ts from a workstation (Node v24.15.0, ICU 78.2) against a production database whose index was written by the app server (Node ≥ 24.16.0, ICU 78.3) fails on every document:
Search index for collection "docs" uses "portable1+nfkc-lower1+icu78.3+locale1+default-en+han-zh+identifiers2+han-bigram1";
expected analyzer "portable1+nfkc-lower1+icu78.2+locale1+default-en+han-zh+identifiers2+han-bigram1".
Rebuild this collection's search index.
Node bumped ICU 78.2 → 78.3 in v24.16.0 (nodejs/node#62324), so this now bites anyone whose local Node patch version differs from the server's — a routine situation.
Why the current behavior is risky, not just inconvenient
The error's advice — "Rebuild this collection's search index" — is actively dangerous when the mismatched party is a client machine. Rebuilding from the workstation would restamp the production index as icu78.2, and the production app would then fail this same check on every write. The safe fix (align the client's Node version with the server's) is not mentioned.
Ideas to consider
Improve the error message: state that the ICU component comes from the running Node version, and that the usual fix is to run the writer with the same Node/ICU as whatever owns the index — rebuild only from the serving environment.
Reconsider fingerprint granularity: ICU patch releases (78.2 → 78.3) rarely change segmentation behavior. Options: fingerprint only the ICU major version, or keep strict matching but downgrade patch-level mismatch to a warning (possibly behind a flag).
Escape hatch: an explicit opt-in (env var or CLI flag) to accept a fingerprint mismatch for one-off imports, clearly documented as "you accept possibly inconsistent tokenization until the next rebuild".
Docs: note in the import/search docs that offline writers (import scripts, CI) must match the serving app's Node version.
Completed and reviewed in local commit ecd8a7c. PostgreSQL and MySQL mismatch errors and recovery documentation now instruct operators to align Node/ICU and analyzer configuration with the serving application before rebuilding. Intentional analyzer changes and unversioned indexes must be rebuilt from the serving environment. Fingerprint checks and structured error fields remain unchanged. Closing at maintainer request; the commit has not been pushed in this session.
Activity
58bits commentedon Oct 17, 2026
Completed and reviewed in local commit ecd8a7c. PostgreSQL and MySQL mismatch errors and recovery documentation now instruct operators to align Node/ICU and analyzer configuration with the serving application before rebuilding. Intentional analyzer changes and unversioned indexes must be rebuilt from the serving environment. Fingerprint checks and structured error fields remain unchanged. Closing at maintainer request; the commit has not been pushed in this session.
fix(search): clarified analyzer fingerprint mismatch recovery (#75)