{"record":{"id":"0ab449609b2cb89d","repo":"cocoindex-io/cocoindex","slug":"valkey-glide-2-4-0-is-required-to-use-the-valkey","errorCode":null,"errorMessage":"valkey-glide>=2.4.0 is required to use the Valkey connector. Please install cocoindex[valkey].","messagePattern":"valkey-glide>=2\\.4\\.0 is required to use the Valkey connector\\. Please install cocoindex\\[valkey\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/valkey/_target.py","lineNumber":46,"sourceCode":"        DistanceMetricType,\n        Field,\n        FtCreateOptions,\n        GlideClient,\n        GlideClientConfiguration,  # noqa: F401 — re-exported\n        NodeAddress,\n        NumericField,\n        RequestError,\n        TagField,\n        TextField,\n        VectorAlgorithm,\n        VectorField,\n        VectorFieldAttributesFlat,\n        VectorFieldAttributesHnsw,\n        VectorType,\n    )\n    from glide.async_commands import ft\nexcept ImportError as e:\n    raise ImportError(\n        \"valkey-glide>=2.4.0 is required to use the Valkey connector. \"\n        \"Please install cocoindex[valkey].\"\n    ) from e\n\nimport cocoindex as coco\nfrom cocoindex.connectorkits import statediff, target\nfrom cocoindex.connectorkits.fingerprint import fingerprint_object\nfrom cocoindex.resources import schema as res_schema\nfrom cocoindex._internal.context_keys import ContextKey, ContextProvider\nfrom cocoindex._internal.datatype import TypeChecker\n\n\n# ---------------------------------------------------------------------------\n# Public types\n# ---------------------------------------------------------------------------\n\n\nclass VectorDef(NamedTuple):","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/valkey/_target.py#L28-L64","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\npip install cocoindex\n\n// after\npip install \"cocoindex[valkey]\"","handlingStrategy":"fallback","validationCode":"import importlib.metadata as _md\ntry:\n    v = _md.version(\"valkey-glide\")\n    assert tuple(map(int, v.split('.')[:2])) >= (2, 4), \"valkey-glide >= 2.4.0 required\"\nexcept _md.PackageNotFoundError:\n    raise SystemExit(\"Install cocoindex[valkey]\")","typeGuard":null,"tryCatchPattern":"try:\n    from cocoindex.connectors import valkey\nexcept ImportError as e:\n    if \"valkey-glide\" in str(e):\n        raise SystemExit(\"Run: pip install 'cocoindex[valkey]'\") from e\n    raise","preventionTips":["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"],"tags":["python","dependency","import-error","valkey"],"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"}