{"record":{"id":"1a42d7c1dbafc925","repo":"cocoindex-io/cocoindex","slug":"neo4j-is-required-to-use-the-neo4j-connector-plea","errorCode":null,"errorMessage":"neo4j is required to use the Neo4j connector. Please install cocoindex[neo4j].","messagePattern":"neo4j is required to use the Neo4j connector\\. Please install cocoindex\\[neo4j\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/neo4j/_target.py","lineNumber":42,"sourceCode":"import uuid as uuid_mod\nfrom 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 neo4j as _neo4j  # type: ignore[import-not-found]\nexcept ImportError as e:\n    raise ImportError(\n        \"neo4j is required to use the Neo4j connector. Please install cocoindex[neo4j].\"\n    ) from e\n\nif TYPE_CHECKING:\n    AsyncDriver = Any\nelse:\n    AsyncDriver = _neo4j.AsyncDriver\n\nimport msgspec\nimport numpy as np\n\nimport cocoindex as coco\nfrom cocoindex._internal.context_keys import ContextKey, ContextProvider\nfrom cocoindex._internal.datatype import (\n    AnyType,\n    MappingType,\n    RecordType,\n    SequenceType,","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/neo4j/_target.py#L24-L60","documentation":"This ImportError is raised at module import time when the neo4j Python driver package is not installed but the Neo4j connector module is imported. The neo4j driver is an optional dependency of cocoindex, enabled via the cocoindex[neo4j] extra. The import is wrapped so the failure surfaces with an actionable message instead of a bare ModuleNotFoundError.","triggerScenarios":"Importing python/cocoindex/connectors/neo4j/_target.py (or the neo4j connector package) in an environment where the neo4j package was never installed — e.g. cocoindex installed as `pip install cocoindex` without extras, or in a fresh venv missing the extra.","commonSituations":"Deploying to production without the optional extra; switching virtualenvs and forgetting dev dependency groups; a Dockerfile that installs base requirements only; CI running tests that import the connector.","solutions":["Install with the extra: pip install 'cocoindex[neo4j]' (or uv add 'cocoindex[neo4j]').","Verify installation: python -c \"import neo4j\".","If neo4j support is unneeded, avoid importing the neo4j connector module/entry point."],"exampleFix":"// before\npip install cocoindex\n// after\npip install \"cocoindex[neo4j]\"","handlingStrategy":"fallback","validationCode":"import importlib.util\nif importlib.util.find_spec(\"neo4j\") is None:\n    raise SystemExit(\"Install the Neo4j driver: pip install 'cocoindex[neo4j]'\")","typeGuard":null,"tryCatchPattern":"try:\n    from cocoindex.connectors import neo4j\nexcept ImportError as e:\n    raise SystemExit(\"Neo4j support missing. Run: pip install 'cocoindex[neo4j]'\") from e","preventionTips":["Always install optional connectors via extras in pyproject/requirements","Pin cocoindex[neo4j] in CI and Docker images","Smoke-test imports of all used connectors at app startup"],"tags":["neo4j","import-error","dependency","optional-dependency"],"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"}