{"record":{"id":"23be847e13f8e367","repo":"cocoindex-io/cocoindex","slug":"turbopuffer-is-required-to-use-the-turbopuffer-con","errorCode":null,"errorMessage":"turbopuffer is required to use the Turbopuffer connector. Please install cocoindex[turbopuffer].","messagePattern":"turbopuffer is required to use the Turbopuffer connector\\. Please install cocoindex\\[turbopuffer\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/turbopuffer/_target.py","lineNumber":31,"sourceCode":"from __future__ import annotations\n\nfrom dataclasses import dataclass\nfrom typing import (\n    Any,\n    Collection,\n    Generic,\n    Literal,\n    NamedTuple,\n    Sequence,\n)\n\nimport msgspec\nimport numpy as np\n\ntry:\n    from turbopuffer import AsyncTurbopuffer, NotFoundError  # type: ignore\nexcept ImportError as e:\n    raise ImportError(\n        \"turbopuffer is required to use the Turbopuffer connector. \"\n        \"Please install cocoindex[turbopuffer].\"\n    ) from e\n\nimport cocoindex as coco\nfrom cocoindex.connectorkits import statediff, target\nfrom cocoindex.connectorkits.fingerprint import fingerprint_object\nfrom cocoindex._internal.datatype import TypeChecker\nfrom cocoindex.resources import schema as res_schema\nfrom cocoindex._internal.context_keys import ContextKey, ContextProvider\n\n\n# Type aliases\n_RowId = str | int\n_RowFingerprint = bytes\n_ROW_ID_CHECKER: TypeChecker[str | int] = TypeChecker(str | int)  # type: ignore[arg-type]\n\n","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/turbopuffer/_target.py#L13-L49","documentation":"The turbopuffer connector depends on the optional third-party `turbopuffer` Python package. Importing the connector module executes a try/except around `from turbopuffer import ...`, and when the package is missing it re-raises an ImportError telling you to install the `cocoindex[turbopuffer]` extra.","triggerScenarios":"Any import of `cocoindex.connectors.turbopuffer` (e.g. `from cocoindex.connectors import turbopuffer`) in an environment where the `turbopuffer` distribution is not installed.","commonSituations":"Installing plain `cocoindex` instead of `cocoindex[turbopuffer]`; a fresh CI/dev environment without the extra; adding the import in code after switching machines; pinned requirements missing the optional dependency.","solutions":["Install the extra: `pip install \"cocoindex[turbopuffer]\"` (or `uv add \"cocoindex[turbopuffer]\"`).","Or install the package directly: `pip install turbopuffer`.","Update requirements/pyproject so the extra is included in the environment that runs the pipeline.","Verify with `python -c \"import turbopuffer\"` before re-running."],"exampleFix":"// before (shell)\npip install cocoindex\n// after (shell)\npip install \"cocoindex[turbopuffer]\"","handlingStrategy":"fallback","validationCode":"import importlib.util\nif importlib.util.find_spec(\"turbopuffer\") is None:\n    raise SystemExit(\"Install the extra: pip install 'cocoindex[turbopuffer]'\")","typeGuard":"def turbopuffer_available() -> bool:\n    import importlib.util\n    return importlib.util.find_spec(\"turbopuffer\") is not None","tryCatchPattern":"try:\n    from cocoindex.connectors import turbopuffer\nexcept ImportError as e:\n    if \"cocoindex[turbopuffer]\" in str(e):\n        raise SystemExit(\"Run: pip install 'cocoindex[turbopuffer]'\") from e\n    raise","preventionTips":["Install optional extras in CI and dev: cocoindex[turbopuffer].","Pin the extra in pyproject/requirements for every environment that imports the connector.","Guard imports at module top so failures surface at startup, not mid-pipeline.","Run `python -c \"import turbopuffer\"` in a smoke test."],"tags":["python","import-error","dependency","turbopuffer"],"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"}