chroma-core/chroma · error · ValueError

You are using a deprecated configuration of Chroma. [

Error message

You are using a deprecated configuration of Chroma.

If you do not have data you wish to migrate, you only need to change how you construct
your Chroma client. Please see the "New Clients" section of https://docs.trychroma.com/deployment/migration.
________________________________________________________________________________________________

If you do have data you wish to migrate, we have a migration tool you can use in order to
migrate your data to the new Chroma architecture.
Please `pip install chroma-migrate` and run `chroma-migrate` to migrate your data and then
change how you construct your Chroma client.

See https://docs.trychroma.com/deployment/migration for more information or join our discord at https://discord.gg/MMeYNTmh3x for help!

What it means

Settings.__getitem__ checks every accessed value against _legacy_config_values - the removed pre-1.0 config values ('duckdb', 'duckdb+parquet', 'clickhouse', 'local', 'rest', old DuckDB/ClickHouse impl classes, 'chromadb.api.local.LocalAPI'). If any read setting holds one of these, Chroma raises this colored banner ValueError instead of silently misbehaving. It means some code - yours, a tutorial's, or a dependency's - still configures Chroma the 0.4.x way.

Source

Thrown at chromadb/config.py:317

    )

    # =======
    # Methods
    # =======

    def require(self, key: str) -> Any:
        """Return the value of a required config key, or raise an exception if it is not
        set"""
        val = self[key]
        if val is None:
            raise ValueError(f"Missing required config value '{key}'")
        return val

    def __getitem__(self, key: str) -> Any:
        val = getattr(self, key)
        # Error on legacy config values
        if isinstance(val, str) and val in _legacy_config_values:
            raise ValueError(LEGACY_ERROR)
        return val

    model_config = {"env_file": ".env", "env_file_encoding": "utf-8", "extra": "ignore"}


T = TypeVar("T", bound="Component")


class Component(ABC, EnforceOverrides):
    _dependencies: Set["Component"]
    _system: "System"
    _running: bool

    def __init__(self, system: "System"):
        self._dependencies = set()
        self._system = system
        self._running = False

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Stop setting chroma_db_impl and the legacy impl values; use the new client constructors - PersistentClient() for embedded, HttpClient() for remote.
  2. Unset stale environment variables: unset CHROMA_DB_IMPL and remove it from Docker/compose/CI definitions.
  3. If you have 0.4.x data to keep, run `pip install chroma-migrate && chroma-migrate` first, then switch to the new client construction.

Example fix

// before
import chromadb
client = chromadb.Client(chromadb.config.Settings(chroma_db_impl='duckdb+parquet', persist_directory='./chroma'))

// after
import chromadb
client = chromadb.PersistentClient(path='./chroma')
Defensive patterns

Strategy: validation

Validate before calling

LEGACY_VALUES = {
    'duckdb', 'duckdb+parquet', 'clickhouse', 'local', 'rest',
    'chromadb.db.duckdb.DuckDB', 'chromadb.db.duckdb.PersistentDuckDB',
    'chromadb.db.clickhouse.Clickhouse', 'chromadb.api.local.LocalAPI',
}
offending = {k: v for k, v in settings.model_dump().items() if v in LEGACY_VALUES}
if offending:
    raise RuntimeError(f'remove legacy Chroma settings before starting: {offending}')

Try / catch

try:
    val = settings['chroma_db_impl']
except ValueError as e:
    if 'deprecated configuration' in str(e):
        raise RuntimeError('legacy 0.4.x config detected - migrate construction and data (chroma-migrate)') from e
    raise

Prevention

When it happens

Trigger: Settings(chroma_db_impl='duckdb+parquet') or chroma_api_impl='chromadb.api.local.LocalAPI'; exported CHROMA_DB_IMPL=duckdb+parquet env vars from an old install; code copied from pre-1.0 tutorials; a wrapper library still passing legacy keys.

Common situations: Upgrading chromadb 0.4.x -> 1.x with stale env vars in shell profiles, Docker images, or docker-compose; CI caches carrying old .env files; teams copying legacy Getting Started snippets.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/a4df9a84ee9aa598. Report an issue: GitHub.