cocoindex-io/cocoindex · error · ImportError

lancedb and pyarrow are required to use the LanceDB connecto

Error message

lancedb and pyarrow are required to use the LanceDB connector. Please install cocoindex[lancedb].

What it means

Importing the LanceDB target connector module fails because the optional packages lancedb and/or pyarrow are missing. CocoIndex raises an ImportError at module import with guidance to install the cocoindex[lancedb] extra.

Source

Thrown at python/cocoindex/connectors/lancedb/_target.py:33

from typing import (
    Any,
    Callable,
    Collection,
    Generic,
    Literal,
    NamedTuple,
    Sequence,
    cast,
)

from typing_extensions import TypeVar

try:
    import lancedb  # type: ignore
    import lancedb.index as lancedb_index  # type: ignore
    import pyarrow as pa  # type: ignore
except ImportError as e:
    raise ImportError(
        "lancedb and pyarrow are required to use the LanceDB connector. Please install cocoindex[lancedb]."
    ) from e

from lancedb.db import AsyncConnection as LanceAsyncConnection  # type: ignore

import numpy as np

import cocoindex as coco
from cocoindex.connectorkits import statediff, target
from cocoindex.connectorkits.fingerprint import fingerprint_object
from cocoindex._internal.datatype import (
    AnyType,
    MappingType,
    SequenceType,
    RecordType,
    TypeChecker,
    UnionType,
    analyze_type_info,

View on GitHub (pinned to e84aa99b32)

Solutions

Install the extra: `pip install 'cocoindex[lancedb]'`.
If partially installed, ensure both packages import: `python -c "import lancedb, pyarrow"`; reinstall whichever fails.
Pin compatible lancedb/pyarrow versions if a recent lancedb broke the import.

Example fix

// before
from cocoindex.connectors.lancedb import LanceDBTarget  # ImportError at import time
// after
# pip install 'cocoindex[lancedb]'
from cocoindex.connectors.lancedb import LanceDBTarget

Defensive patterns

Strategy: try-catch

Validate before calling

try:
    import lancedb, pyarrow  # noqa: F401
except ImportError:
    raise SystemExit("Install the LanceDB extra: pip install 'cocoindex[lancedb]'")

Try / catch

try:
    from cocoindex.connectors.lancedb import LanceDbTarget
except ImportError as e:
    if "lancedb" in str(e) or "pyarrow" in str(e):
        raise SystemExit("Install: pip install 'cocoindex[lancedb]'") from e
    raise

Prevention

Use the cocoindex[lancedb] extra rather than installing lancedb manually.
Keep lancedb and pyarrow versions in the same lockfile.
CI smoke-test the import before deployment.

When it happens

Trigger: Any import of python/cocoindex/connectors/lancedb/_target.py (or the lancedb connectors package) when `import lancedb`, `import lancedb.index`, or `import pyarrow` raises ImportError.

Common situations: Installing cocoindex without [lancedb]; partial environments where pyarrow is present but lancedb is not (or vice versa); broken lancedb/pyarrow installs that fail on import.

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/76bcff9326ecafb7. Report an issue: GitHub.