cocoindex-io/cocoindex · error · ImportError

surrealdb is required to use the SurrealDB connector. Please

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.

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)

Solutions

1. Run: pip install 'cocoindex[surrealdb]' to install the surrealdb client.
2. Or install the client directly: pip install surrealdb.
3. 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

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

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

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

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

• aiobotocore is required to use the Amazon S3 source connecto
• aiomysql is required for async Doris connections. Install it
• sqlite-vec is required for vector support. Install it with:
• Inconsistent cocoindex installation detected: - {p} Pytho
• Failed to load module '{module_ref}'

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/9413092967e2e680. Report an issue: GitHub.