{"record":{"id":"a4df9a84ee9aa598","repo":"chroma-core/chroma","slug":"91myou-are-using-a-deprecated-configuration-of-c","errorCode":null,"errorMessage":"\u001b[91mYou are using a deprecated configuration of Chroma.\n\n\u001b[94mIf you do not have data you wish to migrate, you only need to change how you construct\nyour Chroma client. Please see the \"New Clients\" section of https://docs.trychroma.com/deployment/migration.\n________________________________________________________________________________________________\n\nIf you do have data you wish to migrate, we have a migration tool you can use in order to\nmigrate your data to the new Chroma architecture.\nPlease `pip install chroma-migrate` and run `chroma-migrate` to migrate your data and then\nchange how you construct your Chroma client.\n\nSee https://docs.trychroma.com/deployment/migration for more information or join our discord at https://discord.gg/MMeYNTmh3x for help!\u001b[0m","messagePattern":"\u001b\\[91mYou are using a deprecated configuration of Chroma\\.\n\n\u001b\\[94mIf you do not have data you wish to migrate, you only need to change how you construct\nyour Chroma client\\. Please see the \"New Clients\" section of https://docs\\.trychroma\\.com/deployment/migration\\.\n________________________________________________________________________________________________\n\nIf you do have data you wish to migrate, we have a migration tool you can use in order to\nmigrate your data to the new Chroma architecture\\.\nPlease `pip install chroma-migrate` and run `chroma-migrate` to migrate your data and then\nchange how you construct your Chroma client\\.\n\nSee https://docs\\.trychroma\\.com/deployment/migration for more information or join our discord at https://discord\\.gg/MMeYNTmh3x for help!\u001b\\[0m","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/config.py","lineNumber":317,"sourceCode":"    )\n\n    # =======\n    # Methods\n    # =======\n\n    def require(self, key: str) -> Any:\n        \"\"\"Return the value of a required config key, or raise an exception if it is not\n        set\"\"\"\n        val = self[key]\n        if val is None:\n            raise ValueError(f\"Missing required config value '{key}'\")\n        return val\n\n    def __getitem__(self, key: str) -> Any:\n        val = getattr(self, key)\n        # Error on legacy config values\n        if isinstance(val, str) and val in _legacy_config_values:\n            raise ValueError(LEGACY_ERROR)\n        return val\n\n    model_config = {\"env_file\": \".env\", \"env_file_encoding\": \"utf-8\", \"extra\": \"ignore\"}\n\n\nT = TypeVar(\"T\", bound=\"Component\")\n\n\nclass Component(ABC, EnforceOverrides):\n    _dependencies: Set[\"Component\"]\n    _system: \"System\"\n    _running: bool\n\n    def __init__(self, system: \"System\"):\n        self._dependencies = set()\n        self._system = system\n        self._running = False\n","sourceCodeStart":299,"sourceCodeEnd":335,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/config.py#L299-L335","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Stop setting chroma_db_impl and the legacy impl values; use the new client constructors - PersistentClient() for embedded, HttpClient() for remote.","Unset stale environment variables: unset CHROMA_DB_IMPL and remove it from Docker/compose/CI definitions.","If you have 0.4.x data to keep, run `pip install chroma-migrate && chroma-migrate` first, then switch to the new client construction."],"exampleFix":"// before\nimport chromadb\nclient = chromadb.Client(chromadb.config.Settings(chroma_db_impl='duckdb+parquet', persist_directory='./chroma'))\n\n// after\nimport chromadb\nclient = chromadb.PersistentClient(path='./chroma')","handlingStrategy":"validation","validationCode":"LEGACY_VALUES = {\n    'duckdb', 'duckdb+parquet', 'clickhouse', 'local', 'rest',\n    'chromadb.db.duckdb.DuckDB', 'chromadb.db.duckdb.PersistentDuckDB',\n    'chromadb.db.clickhouse.Clickhouse', 'chromadb.api.local.LocalAPI',\n}\noffending = {k: v for k, v in settings.model_dump().items() if v in LEGACY_VALUES}\nif offending:\n    raise RuntimeError(f'remove legacy Chroma settings before starting: {offending}')","typeGuard":null,"tryCatchPattern":"try:\n    val = settings['chroma_db_impl']\nexcept ValueError as e:\n    if 'deprecated configuration' in str(e):\n        raise RuntimeError('legacy 0.4.x config detected - migrate construction and data (chroma-migrate)') from e\n    raise","preventionTips":["Grep codebase and CI definitions for chroma_db_impl and the legacy impl strings before upgrading to 1.x.","Construct clients via PersistentClient()/HttpClient()/EphemeralClient() only - never via impl class names.","Keep a smoke test that boots a client in CI to catch legacy env vars early."],"tags":["configuration","migration","deprecated","upgrade"],"backgroundTag":"deprecated-configuration","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}