{"record":{"id":"a2452c5f6ef6cc32","repo":"cocoindex-io/cocoindex","slug":"falkordb-is-required-to-use-the-falkordb-connector","errorCode":null,"errorMessage":"falkordb is required to use the FalkorDB connector. Please install cocoindex[falkordb].","messagePattern":"falkordb is required to use the FalkorDB connector\\. Please install cocoindex\\[falkordb\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/falkordb/_target.py","lineNumber":39,"sourceCode":"from dataclasses import dataclass\nfrom typing import (\n    TYPE_CHECKING,\n    Any,\n    Callable,\n    Collection,\n    Generic,\n    Literal,\n    NamedTuple,\n    Sequence,\n)\n\nfrom typing_extensions import TypeVar\n\ntry:\n    import falkordb as _falkordb  # noqa: F401  # type: ignore[import-untyped]\n    import falkordb.asyncio as _falkordb_asyncio  # type: ignore[import-untyped]\nexcept ImportError as e:\n    raise ImportError(\n        \"falkordb is required to use the FalkorDB connector. \"\n        \"Please install cocoindex[falkordb].\"\n    ) from e\n\nif TYPE_CHECKING:\n    AsyncFalkorDB = Any\n    AsyncGraph = Any\nelse:\n    AsyncFalkorDB = _falkordb_asyncio.FalkorDB\n    AsyncGraph = Any\n\nimport numpy as np\nimport msgspec\n\nimport cocoindex as coco\nfrom cocoindex.connectorkits import statediff, target\nfrom cocoindex.connectorkits.fingerprint import fingerprint_object\nfrom cocoindex._internal.datatype import (","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/falkordb/_target.py#L21-L57","documentation":"The FalkorDB connector module raises this ImportError at import time when the optional `falkordb` Python package is not installed. CocoIndex ships connector support without the third-party client, requiring an explicit extra install. The guard exists so users get a clear install hint instead of a confusing NameError later.","triggerScenarios":"Importing anything from `python/cocoindex/connectors/falkordb/_target.py` (e.g. `from cocoindex.connectors import falkordb` or calling `falkordb.declare_dir_target`/`table_target`) while `import falkordb` raises ImportError because the package is absent from the environment.","commonSituations":"Fresh virtualenv or CI environment where only the base cocoindex package was installed; deploying to a server and forgetting the extra; switching Python interpreters so the extra is installed in a different env; pinned requirements that list cocoindex without extras.","solutions":["Install the extra: `pip install 'cocoindex[falkordb]'` (or `uv add 'cocoindex[falkordb]'`).","Install the client directly if the extra name differs in your version: `pip install falkordb`.","Verify the package is in the active interpreter: `python -c 'import falkordb'`.","If using a lockfile, regenerate it after adding the extra so deployments include falkordb."],"exampleFix":"// before (pyproject/requirements)\ncocoindex>=1.0\n// after\ncocoindex[falkordb]>=1.0","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec(\"falkordb\") is not None, \"pip install 'cocoindex[falkordb]'\"","typeGuard":null,"tryCatchPattern":"try:\n    from cocoindex.connectors import falkordb\nexcept ImportError:\n    falkordb = None\nif falkordb is None:\n    raise SystemExit(\"Install: pip install 'cocoindex[falkordb]'\")","preventionTips":["Always declare extras in pyproject/requirements: cocoindex[falkordb].","Add a smoke import test in CI that imports the connector module.","Pin and lock dependencies so deploy environments match dev."],"tags":["python","import-error","optional-dependency","falkordb"],"backgroundTag":"missing-optional-dependency","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"}