{"record":{"id":"64e8b819233e5c88","repo":"cocoindex-io/cocoindex","slug":"environment-settings-must-provide-settings-db-path","errorCode":null,"errorMessage":"Environment settings must provide Settings.db_path (or set COCOINDEX_DB environment variable)","messagePattern":"Environment settings must provide Settings\\.db_path \\(or set COCOINDEX_DB environment variable\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/_internal/environment.py","lineNumber":394,"sourceCode":"                    def _close() -> None:\n                        try:\n                            next(sync_gen)\n                        except StopIteration:\n                            pass\n                        finally:\n                            close_fn = getattr(sync_gen, \"close\", None)\n                            if callable(close_fn):\n                                close_fn()\n\n                    exit_stack.callback(_close)\n\n                built_settings = env_builder.settings\n                if not built_settings.db_path:\n                    default_db_path = setting.get_default_db_path()\n                    if default_db_path:\n                        built_settings.db_path = default_db_path\n                    else:\n                        raise ValueError(\n                            \"Environment settings must provide Settings.db_path \"\n                            \"(or set COCOINDEX_DB environment variable)\"\n                        )\n\n                context_provider = env_builder._context_provider\n                self._exit_stack.push_async_callback(context_provider.aclose)\n\n                loop = asyncio.get_running_loop()\n                env = Environment(\n                    built_settings,\n                    name=self._name,\n                    context_provider=context_provider,\n                    event_loop=loop,\n                    exception_handler=env_builder._exception_handler,\n                    info=self._info,\n                )\n                self._env = env\n                return env","sourceCodeStart":376,"sourceCodeEnd":412,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/_internal/environment.py#L376-L412","documentation":"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.","triggerScenarios":"Calling coco.start() / _get_env_sync without Settings.db_path and with the COCOINDEX_DB environment variable unset or empty.","commonSituations":"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).","solutions":["Export COCOINDEX_DB=/path/to/db before starting","Pass db_path explicitly in the environment settings/builder","Load your .env file (dotenv) before calling start()","In CI/containers, add COCOINDEX_DB to the environment configuration"],"exampleFix":"// before\ncoco.start()\n\n// after (shell)\nexport COCOINDEX_DB=./cocoindex.db\ncoco.start()","handlingStrategy":"validation","validationCode":"import os\nassert os.environ.get(\"COCOINDEX_DB\"), \"Set COCOINDEX_DB before starting the environment\"","typeGuard":null,"tryCatchPattern":"try:\n    coco.start()\nexcept ValueError as e:\n    if \"Settings.db_path\" in str(e):\n        os.environ[\"COCOINDEX_DB\"] = \"./cocoindex.db\"\n        coco.start()","preventionTips":["Export COCOINDEX_DB in shell profiles, .env, and CI/container configs","Load dotenv before program start","Check env var spelling (COCOINDEX_DB, not COCOINDEX_DATABASE)"],"tags":["environment","configuration","env-var"],"backgroundTag":"missing-env-var","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}