cocoindex-io/cocoindex · error · ImportError

valkey-glide>=2.4.0 is required to use the Valkey connector.

Error message

valkey-glide>=2.4.0 is required to use the Valkey connector. Please install cocoindex[valkey].

What it means

The Valkey connector depends on the optional `valkey-glide` package (>= 2.4.0), which is not installed with the base cocoindex package. Importing the connector module runs `from glide...` imports inside a try/except; on ImportError it re-raises this ImportError pointing at the `cocoindex[valkey]` extra.

Source

Thrown at python/cocoindex/connectors/valkey/_target.py:46

        DistanceMetricType,
        Field,
        FtCreateOptions,
        GlideClient,
        GlideClientConfiguration,  # noqa: F401 — re-exported
        NodeAddress,
        NumericField,
        RequestError,
        TagField,
        TextField,
        VectorAlgorithm,
        VectorField,
        VectorFieldAttributesFlat,
        VectorFieldAttributesHnsw,
        VectorType,
    )
    from glide.async_commands import ft
except ImportError as e:
    raise ImportError(
        "valkey-glide>=2.4.0 is required to use the Valkey connector. "
        "Please install cocoindex[valkey]."
    ) from e

import cocoindex as coco
from cocoindex.connectorkits import statediff, target
from cocoindex.connectorkits.fingerprint import fingerprint_object
from cocoindex.resources import schema as res_schema
from cocoindex._internal.context_keys import ContextKey, ContextProvider
from cocoindex._internal.datatype import TypeChecker


# ---------------------------------------------------------------------------
# Public types
# ---------------------------------------------------------------------------


class VectorDef(NamedTuple):

View on GitHub (pinned to e84aa99b32)

Solutions

Install the extra: pip install 'cocoindex[valkey]' (or uv add 'cocoindex[valkey]').
If valkey-glide is already installed, upgrade it: pip install -U 'valkey-glide>=2.4.0'.
Verify with python -c "import glide; print(glide.__version__ if hasattr(glide,'__version__') else 'ok')" that the import path resolves.

Example fix

// before
pip install cocoindex

// after
pip install "cocoindex[valkey]"

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.metadata as _md
try:
    v = _md.version("valkey-glide")
    assert tuple(map(int, v.split('.')[:2])) >= (2, 4), "valkey-glide >= 2.4.0 required"
except _md.PackageNotFoundError:
    raise SystemExit("Install cocoindex[valkey]")

Try / catch

try:
    from cocoindex.connectors import valkey
except ImportError as e:
    if "valkey-glide" in str(e):
        raise SystemExit("Run: pip install 'cocoindex[valkey]'") from e
    raise

Prevention

Add cocoindex[valkey] to requirements/pyproject extras wherever the Valkey connector is imported
Pin valkey-glide>=2.4.0 explicitly in the environment
Catch the ImportError at app startup with a clear install instruction instead of failing mid-run

When it happens

Trigger: Importing anything from `cocoindex.connectors.valkey` (e.g. `valkey.index_target`) in an environment where `valkey-glide` was never installed, or where a version < 2.4.0 is installed that lacks the imported `ft`/`VectorFieldAttributesHnsw` symbols.

Common situations: Fresh CI or venv where only `pip install cocoindex` was run; following docs that mention the Valkey connector without the extras syntax; an old pinned valkey-glide version that predates the required API.

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/0ab449609b2cb89d. Report an issue: GitHub.