SQLite Version Incompatibility
criticalChroma requires SQLite ≥3.35 for critical features like ALTER TABLE support and improved JSON handling. Older Python versions (< 3.10) or Linux distributions (Ubuntu 20.04, Debian buster) bundle incompatible SQLite versions, causing initialization failures, schema migration errors, and runtime crashes.
Chroma initialization fails with SQLite-related errors during startup. Errors indicate missing SQLite functions, unsupported SQL syntax (ALTER TABLE), or version check failures. Application cannot start or create collections.
1. Detect: Check SQLite version on startup: `python -c 'import sqlite3; print(sqlite3.sqlite_version)'`. Review initialization logs for SQLite errors (ALTER TABLE not supported, unknown functions). 2. Diagnose: Python < 3.10 bundles older SQLite. Linux distributions: Ubuntu 20.04 (SQLite 3.31), Debian buster (SQLite 3.27). Check OS/container base image version. 3. Remediate (Python upgrade): Upgrade to Python 3.10+ which bundles SQLite 3.37+. This is the cleanest solution. 4. Remediate (pysqlite3-binary): Install `pip install pysqlite3-binary` and override default sqlite3: `import sys; sys.modules['sqlite3'] = __import__('pysqlite3')`. This must be done before importing Chroma. 5. Remediate (compile from source): Compile SQLite 3.35+ from source and link Python against it. Most complex but works for legacy Python versions. 6. Remediate (Docker): Use Debian bookworm (12) or Ubuntu 22.04+ base images which include modern SQLite. Update Dockerfile: `FROM python:3.11-bookworm`. 7. Prevent: Document minimum SQLite version in deployment guides. Add version check to startup scripts. Test in target deployment environment before production rollout.