What causes "Settings.db_path must be provided" in cocoindex-io/cocoindex?

Set db_path explicitly: Settings(db_path="/path/to/db")

cocoindex-io/cocoindex · error · ValueError

Settings.db_path must be provided

Error message

Settings.db_path must be provided

What it means

Environment.__init__ requires Settings.db_path to be set — the environment needs a database location for its state. If settings.db_path is falsy at construction time, a ValueError is raised immediately.

Source

Thrown at python/cocoindex/_internal/environment.py:222

    _settings: setting.Settings
    _context_provider: ContextProvider
    _loop_runner: _LoopRunner
    _async_context: core.AsyncContext
    _exception_handler: ExceptionHandler | None
    _info: EnvironmentInfo

    def __init__(
        self,
        settings: setting.Settings,
        *,
        name: str | None = None,
        context_provider: ContextProvider | None = None,
        event_loop: asyncio.AbstractEventLoop | None = None,
        exception_handler: ExceptionHandler | None = None,
        info: EnvironmentInfo | None = None,
    ):
        if not settings.db_path:
            raise ValueError("Settings.db_path must be provided")
        self._name = name or ""
        self._settings = settings
        self._context_provider = context_provider or ContextProvider()

        if event_loop is None:
            event_loop = get_event_loop_or_default()

        if event_loop.is_running():
            self._loop_runner = _LoopRunner.from_running_loop(event_loop)
        else:
            # Keep a loop running for sync users (needed for async callbacks).
            runner = _LoopRunner(event_loop)
            runner.ensure_running()
            self._loop_runner = runner

        self._async_context = core.AsyncContext(self._loop_runner.loop)
        self._core_env = core.Environment(
            settings._to_engine_dict(), self._async_context

View on GitHub (pinned to e84aa99b32)

Solutions

Set db_path explicitly: Settings(db_path="/path/to/db")
Set the COCOINDEX_DB environment variable and build settings via the builder path (_get_env) instead of constructing Settings by hand
Check that the variable holding db_path isn't accidentally empty/None

Example fix

# before
env = coco.Environment("myenv", coco.Settings())

# after
env = coco.Environment("myenv", coco.Settings(db_path="./cocoindex.db"))

Defensive patterns

Strategy: validation

Validate before calling

settings = coco.Settings(db_path=db_path)
assert settings.db_path, "Settings.db_path must be set before creating Environment"

Prevention

Always pass db_path when constructing Settings manually
Prefer the builder/_get_env path which applies the COCOINDEX_DB default
Assert db_path truthiness in test fixtures that build Environments

When it happens

Trigger: Calling Environment(name, Settings(...)) directly with a Settings object whose db_path is empty/None. Note _get_env normally fills db_path from COCOINDEX_DB; constructing Settings manually bypasses that defaulting.

Common situations: Hand-constructing Settings in tests or scripts and forgetting db_path; copying Settings-building code that relies on the env var; refactors that removed db_path assignment.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/f50c7e434ea90705. Report an issue: GitHub.