What causes "Missing required config value '{key}'" in chroma-core/chroma?

Set the value explicitly in the constructor: Settings(migrations_hash_algorithm='sha256') (use whichever key the traceback names).

chroma-core/chroma · error · ValueError

Missing required config value '{key}'

Error message

Missing required config value '{key}'

What it means

Settings.require(key) (chromadb/config.py) is the accessor for settings that must be present - it reads the key and raises ValueError if the value is None. A None means no default exists for that field and nothing supplied it: not the Settings(...) call, not a .env file, not an environment variable. Internal components (e.g. SqliteDB requiring allow_reset, MigratableDB requiring migrations_hash_algorithm) call require() during startup, so this typically fires while a System boots.

Source

Thrown at chromadb/config.py:310

    # ======
    # Legacy
    # ======

    chroma_db_impl: Optional[str] = None
    chroma_collection_assignment_policy_impl: str = (
        "chromadb.ingest.impl.simple_policy.SimpleAssignmentPolicy"
    )

    # =======
    # 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"

View on GitHub (pinned to aecdd12c8a)

Solutions

Set the value explicitly in the constructor: Settings(migrations_hash_algorithm='sha256') (use whichever key the traceback names).
Export the matching CHROMA_-prefixed environment variable (e.g. CHROMA_MIGRATIONS_HASH_ALGORITHM).
If the setting is genuinely optional in your flow, read it with settings[key] and handle None yourself instead of require().

Example fix

// before
settings = Settings(persist_directory='./data')  # migrations_hash_algorithm is None
...
settings.require('migrations_hash_algorithm')  # ValueError

// after
settings = Settings(persist_directory='./data', migrations_hash_algorithm='sha256')
settings.require('migrations_hash_algorithm')

Defensive patterns

Strategy: validation

Validate before calling

key = 'migrations_hash_algorithm'  # whichever key you require
if settings[key] is None:
    settings = settings.model_copy(update={key: 'sha256'})  # supply a default explicitly
settings.require(key)

Try / catch

try:
    val = settings.require(key)
except ValueError as e:
    raise RuntimeError(
        f'config error: {e}. Set Settings({key}=...) or export the matching CHROMA_ env var.'
    ) from e

Prevention

Build Settings in one factory function per environment so required keys are never missed.
At startup, assert every key you will require() is non-None and fail with a clear message.
Run the process from the directory containing .env, or pass an absolute env_file path.

When it happens

Trigger: Booting a System whose Settings never set a required, default-less key; a misspelled or missing CHROMA_-prefixed env var; a .env file not loaded because the process runs from a different working directory (model_config env_file='.env' is relative); passing Settings() bare in a custom deployment.

Common situations: Custom deployment code that constructs System(Settings()) without setting impl-level keys; env var naming/casing mismatches in Docker or CI; running the app from another directory so the relative .env is not found.

Related errors

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