cocoindex-io/cocoindex · error · ValueError

Environment settings must provide Settings.db_path (or set C

Error message

Environment settings must provide Settings.db_path (or set COCOINDEX_DB environment variable)

What it means

During environment creation (_get_env, used by _get_env_sync and start), the builder's settings get a default db_path from get_default_db_path() (which reads COCOINDEX_DB). If neither the built settings nor the environment variable supplies one, ValueError is raised.

Source

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

                    def _close() -> None:
                        try:
                            next(sync_gen)
                        except StopIteration:
                            pass
                        finally:
                            close_fn = getattr(sync_gen, "close", None)
                            if callable(close_fn):
                                close_fn()

                    exit_stack.callback(_close)

                built_settings = env_builder.settings
                if not built_settings.db_path:
                    default_db_path = setting.get_default_db_path()
                    if default_db_path:
                        built_settings.db_path = default_db_path
                    else:
                        raise ValueError(
                            "Environment settings must provide Settings.db_path "
                            "(or set COCOINDEX_DB environment variable)"
                        )

                context_provider = env_builder._context_provider
                self._exit_stack.push_async_callback(context_provider.aclose)

                loop = asyncio.get_running_loop()
                env = Environment(
                    built_settings,
                    name=self._name,
                    context_provider=context_provider,
                    event_loop=loop,
                    exception_handler=env_builder._exception_handler,
                    info=self._info,
                )
                self._env = env
                return env

View on GitHub (pinned to e84aa99b32)

Solutions

1. Export COCOINDEX_DB=/path/to/db before starting
2. Pass db_path explicitly in the environment settings/builder
3. Load your .env file (dotenv) before calling start()
4. In CI/containers, add COCOINDEX_DB to the environment configuration

Example fix

// before
coco.start()

// after (shell)
export COCOINDEX_DB=./cocoindex.db
coco.start()

import os
assert os.environ.get("COCOINDEX_DB"), "Set COCOINDEX_DB before starting the environment"

try:
    coco.start()
except ValueError as e:
    if "Settings.db_path" in str(e):
        os.environ["COCOINDEX_DB"] = "./cocoindex.db"
        coco.start()

When it happens

Trigger: Calling coco.start() / _get_env_sync without Settings.db_path and with the COCOINDEX_DB environment variable unset or empty.

Common situations: Fresh checkout/CI without the env var exported; .env file not loaded; running in a container where COCOINDEX_DB wasn't passed through; typo'd variable name (COCOINDEX_DATABASE).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• {env_name} is not set
• failed to parse environment variable {env_name}: {value}
• An app named '{name}' is already registered in this environm
• Settings.db_path must be provided
• Specify either `db_settings=` or the legacy `lmdb_max_dbs=`/

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