cocoindex-io/cocoindex · error · ImportError

falkordb is required to use the FalkorDB connector. Please i

Error message

falkordb is required to use the FalkorDB connector. Please install cocoindex[falkordb].

What it means

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.

Source

Thrown at python/cocoindex/connectors/falkordb/_target.py:39

from dataclasses import dataclass
from typing import (
    TYPE_CHECKING,
    Any,
    Callable,
    Collection,
    Generic,
    Literal,
    NamedTuple,
    Sequence,
)

from typing_extensions import TypeVar

try:
    import falkordb as _falkordb  # noqa: F401  # type: ignore[import-untyped]
    import falkordb.asyncio as _falkordb_asyncio  # type: ignore[import-untyped]
except ImportError as e:
    raise ImportError(
        "falkordb is required to use the FalkorDB connector. "
        "Please install cocoindex[falkordb]."
    ) from e

if TYPE_CHECKING:
    AsyncFalkorDB = Any
    AsyncGraph = Any
else:
    AsyncFalkorDB = _falkordb_asyncio.FalkorDB
    AsyncGraph = Any

import numpy as np
import msgspec

import cocoindex as coco
from cocoindex.connectorkits import statediff, target
from cocoindex.connectorkits.fingerprint import fingerprint_object
from cocoindex._internal.datatype import (

View on GitHub (pinned to e84aa99b32)

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.

Example fix

// before (pyproject/requirements)
cocoindex>=1.0
// after
cocoindex[falkordb]>=1.0

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
assert importlib.util.find_spec("falkordb") is not None, "pip install 'cocoindex[falkordb]'"

Try / catch

try:
    from cocoindex.connectors import falkordb
except ImportError:
    falkordb = None
if falkordb is None:
    raise SystemExit("Install: pip install 'cocoindex[falkordb]'")

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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