When Your ChromaDB Mutates and You’re Out of Luck

Why Migration Was Necessary

We originally ran ChromaDB <0.7.0 wrapped with langchain_chroma. Back then, things were simple:

• Storage = SQLite
• Everything lived in a modest file
• API surface was stable enough to lull you into false confidence
• LangChain handled the wrapper logic without screaming

Then came ChromaDB 1.x. A rewrite. A reinvention. A complete flip of the table.

Breaking changes included:

• SQLite backend replaced with Parquet / DuckDB hybrid storage
• Entire internal API reorganized
• Several old methods removed (silently, of course)
• Embedding validation became strict
• LangChain wrappers changed shape
• The new Chroma auto-calls embedding APIs even when you give it precomputed vectors
• Token limits became a real-world hazard, not just a theoretical annoyance

Fun fact: in our database, single memory chunks could hit 3–4k tokens. Try recomputing that thousands of times through OpenAI’s embedding endpoint and watch your API key sob uncontrollably.

Here’s the punchline: migrating in-place was impossible. Nothing was compatible anymore — not the files, not the wrappers, not even the Python versions.

The Failures That Made Us Cry (and Swear)

You’d think “use the official migration tool,” right? Hahahah. No.

We tried all obvious paths. Each one was a unique flavor of pain.

error: command '/usr/bin/clang++' failed with exit code 1
Failed building wheel for duckdb
OSError: [Errno 9] Bad file descriptor

ImportError: cannot import name 'API' from 'chromadb.api'

Our Brutal Solution (Because Gentle Solutions Don’t Work Here)

This architecture is based on the principle:

> "If the database refuses to speak your language, make it shut up and hand you JSON."

from langchain_chroma import Chroma
import json

collection = Chroma(collection_name="memory", persist_directory=old_path)
data = collection.get(include=["documents", "embeddings", "metadatas"])

export_data = {
    "memory": {
        "ids": [m["id"] for m in data["metadatas"]],
        "documents": data["documents"],
        "embeddings": [e.tolist() for e in data["embeddings"]],
        "metadatas": data["metadatas"]
    }
}

with open("chroma_export.json", "w", encoding="utf-8") as f:
    json.dump(export_data, f, ensure_ascii=False, indent=2)

from langchain.embeddings.base import Embeddings

class DummyEmbeddings(Embeddings):
    def embed_documents(self, texts):
        return [[0.0]] * len(texts)
    def embed_query(self, text):
        return [0.0]

collection._collection.add(
    documents=data["documents"],
    metadatas=data["metadatas"],
    embeddings=data["embeddings"],
    ids=data["ids"]
)

import subprocess
import sys

def run(cmd):
    print("[CMD]", " ".join(cmd))
    subprocess.check_call(cmd)

run([sys.executable, "export_old_chroma.py", "--old-path", old_path, "--output", output_json])
run([sys.executable, "import_new_chroma.py", "--new-path", new_path, "--input", output_json])

Why This Works and chroma-migrate Doesn’t

1. No DuckDB wheel compilation
2. No legacy internal API usage
3. No OpenAI calls
4. No token overflows
5. No LangChain auto-embedding nonsense
6. Works on Python 3.13, macOS ARM, CI, Docker
7. Guaranteed ID + metadata consistency
8. JSON is easy to diff, verify, version, compress

Migrating via JSON gives you full control. Everything else gives you full pain.

Additional Deep-Dive: Why ChromaDB Became So incompatible

A few architectural points for the curious:

• ChromaDB moved away from a pure key-value SQLite structure
• Instead it adopted a columnar, analytics-friendly storage model
• Parquet + DuckDB enables huge vector stores (millions of rows)
• But the migration from one to another is not isomorphic

SQLite stores:

• rows
• with arbitrary JSON blobs
• with minimal validation
• ideal for small agent memories

Parquet stores:

• typed columns
• strict schemas
• strong null/value constraints
• often incompatible with arbitrary, messy metadata

Thus the real root cause: ChromaDB 0.x and 1.x don’t share a common schema language.

Therefore JSON intermediate format is the only sane choice.

Lessons Learned

• Never trust official migration tools for fast-evolving libraries
• Private APIs are private only until you need them
• JSON is the Switzerland of data formats
• Precomputed embeddings are priceless — protect them
• Token limits are real, and they are coming for you
• If migration is painful, automate it
• If migration breaks, automate the breakage
• If all else fails, bring BOFH energy and write your own script

In the end, ChromaDB mutated. LangChain mutated. Python mutated. Nothing worked.

But with a little JSON, a dummy embeddings class, and the willingness to use private APIs like a true sysadmin sociopath…

our AI memories survived.

And that’s all that matters.

Full code you can find in the Repo. If you found this guide helpful, consider supporting my work via BuyMeACoffee, ThanksDev, or DonationAlerts! Your support fuels more deep dives into the wild world of AI engineering. Thank you!