Bugfix & Compatibility Workarounds
Session-specific bug fixes and version-compatibility workarounds for third-party libraries. Each entry is a named, reproducible problem + a verified workaround. When you hit a third-party library error that doesn't match current docs, check this hub first.
Quick Routing
| Symptom / Library Version | Reference |
|---|---|
ChromaDB 0.4.x + NumPy 2.x → AttributeError: np.float_/np.int_ (Apple Silicon / Docker) |
→ references/***SECRET***.md |
ChromaDB 0.4.x → query()/peek()/count() all fail with seq_id BLOB |
→ references/chromadb-seq-id-blob-fix.md |
| ChromaDB Settings + Pydantic v2 → "extra fields not permitted" | → references/pydantic-v1-v2-chromadb-fix.md |
Python 3.9 → TypeError: unsupported operand type(s) for |: 'types.GenericAlias' and 'NoneType' (PEP 604 union syntax) |
→ references/python39-union-syntax.md |
jsdom (vitest) tests fail with TypeError: RequestInit: Expected signal ("AbortSignal {}") to be an instance of AbortSignal — Node ≥20/24 undici brand check rejects jsdom's AbortSignal in new Request(url, { signal }) |
→ references/***SECRET***.md |
pydantic-settings → code default value ignored, app serves stale version number from .env |
→ references/pydantic-env-override.md |
vitest jsdom + Node ≥19 built-in undici → react-router createMemoryRouter tests die with Unhandled Rejection RequestInit: Expected signal (...) to be an instance of AbortSignal |
→ references/***SECRET***.md |
Scripts
scripts/chromadb-rebuild-from-sqlite.py— Rebuild a ChromaDB collection from raw SQLite when seq_id BLOB lockout blocksquery()/peek()/count().
Common Patterns
Diagnose a ChromaDB Failure
Before reinventing a fix, check the three most likely categories:
- NumPy 2.x alias removal — fixes the import error after
pip install -U numpy. Affects ChromaDB ≤ 0.4.22 on Apple Silicon or Linux Docker with NumPy ≥ 2.0. - seq_id BLOB — query() returns empty even though embeddings are in SQLite. Fixed by
scripts/chromadb-rebuild-from-sqlite.pyextracting raw rows and rebuilding the collection with a fresh embedding function. - Pydantic v2 —
extra fields not permittedwhen ChromaDB'sSettingsinherits pydantic v1 in a pydantic-v2 project.
Apply a Fix
Each reference file has: symptom → version table → exact diff/patch → verification step.
How to Add a New Fix
When you hit a NEW reproducible third-party bug and have a verified workaround:
- Create
references/<library>-<symptom>.mdwith the recipe (problem, version table, fix, verify). - Add a row to the Quick Routing table above.
- (Optional) Add scripts under
scripts/for statically-runnable workarounds.
This keeps each fix one-click-findable without bloating a single mega-file.