cocoindex-io/cocoindex · error · ImportError

surrealdb is required to use the SurrealDB connector…

Error message

surrealdb is required to use the SurrealDB connector. Please install cocoindex[surrealdb].

What it means

The SurrealDB connector module imports the optional surrealdb client package at module load time. If it is not installed, importing the connector fails immediately with an ImportError telling the user to install the cocoindex[surrealdb] extra.

Solutions

Run: pip install 'cocoindex[surrealdb]' to install the surrealdb client.
Or install the client directly: pip install surrealdb.
If using uv: uv add surrealdb (or add the cocoindex extra) to your project.

Example fix

// before (ImportError on import)
from cocoindex.connectors import surrealdb
// after
# pip install 'cocoindex[surrealdb]'
from cocoindex.connectors import surrealdb

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
if importlib.util.find_spec("surrealdb") is None:
    raise SystemExit("surrealdb missing; run: pip install 'cocoindex[surrealdb]'")

Type guard

def surrealdb_available() -> bool:
    import importlib.util
    return importlib.util.find_spec("surrealdb") is not None

Try / catch

try:
    from cocoindex.connectors import surrealdb
except ImportError as e:
    if "cocoindex[surrealdb]" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "cocoindex[surrealdb]"], check=True)
        from cocoindex.connectors import surrealdb

Prevention

Use the cocoindex[surrealdb] extra in your dependency file, not bare cocoindex.
Fail fast with a dependency check at app startup.
Keep dev and prod dependency lists in sync (lock files).

When it happens

Trigger: Importing cocoindex.connectors.surrealdb (or any module importing it) in an environment where the surrealdb package is absent, e.g. after `pip install cocoindex` without the [surrealdb] extra, or in a fresh venv/CI job.

Common situations: Following docs without installing extras; deploying to production with a minimal requirements file that omitted the extra; switching Python environments where the dev env had it installed.

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/9413092967e2e680. Report an issue: GitHub.

Appendix: source

Thrown at python/cocoindex/connectors/surrealdb/_target.py:36

import uuid
from dataclasses import dataclass
from typing import (
    TYPE_CHECKING,
    Any,
    Callable,
    Collection,
    Generic,
    Literal,
    NamedTuple,
    Sequence,
)

from typing_extensions import TypeVar

try:
    import surrealdb as _surrealdb  # type: ignore[import-untyped]
except ImportError as e:
    raise ImportError(
        "surrealdb is required to use the SurrealDB connector. "
        "Please install cocoindex[surrealdb]."
    ) from e

if TYPE_CHECKING:
    # surrealdb is untyped; use Any so mypy doesn't complain about attribute access.
    AsyncSurreal = Any
else:
    AsyncSurreal = _surrealdb.AsyncSurreal

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,

View on GitHub (pinned to e84aa99b32)