{"record":{"id":"9413092967e2e680","repo":"cocoindex-io/cocoindex","slug":"surrealdb-is-required-to-use-the-surrealdb-connect","errorCode":null,"errorMessage":"surrealdb is required to use the SurrealDB connector. Please install cocoindex[surrealdb].","messagePattern":"surrealdb is required to use the SurrealDB connector\\. Please install cocoindex\\[surrealdb\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/surrealdb/_target.py","lineNumber":36,"sourceCode":"import uuid\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 surrealdb as _surrealdb  # type: ignore[import-untyped]\nexcept ImportError as e:\n    raise ImportError(\n        \"surrealdb is required to use the SurrealDB connector. \"\n        \"Please install cocoindex[surrealdb].\"\n    ) from e\n\nif TYPE_CHECKING:\n    # surrealdb is untyped; use Any so mypy doesn't complain about attribute access.\n    AsyncSurreal = Any\nelse:\n    AsyncSurreal = _surrealdb.AsyncSurreal\n\nimport numpy as np\n\nimport cocoindex as coco\nfrom cocoindex.connectorkits import statediff, target\nfrom cocoindex.connectorkits.fingerprint import fingerprint_object\nfrom cocoindex._internal.datatype import (\n    AnyType,\n    MappingType,","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/surrealdb/_target.py#L18-L54","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (ImportError on import)\nfrom cocoindex.connectors import surrealdb\n// after\n# pip install 'cocoindex[surrealdb]'\nfrom cocoindex.connectors import surrealdb","handlingStrategy":"try-catch","validationCode":"import importlib.util\nif importlib.util.find_spec(\"surrealdb\") is None:\n    raise SystemExit(\"surrealdb missing; run: pip install 'cocoindex[surrealdb]'\")","typeGuard":"def surrealdb_available() -> bool:\n    import importlib.util\n    return importlib.util.find_spec(\"surrealdb\") is not None","tryCatchPattern":"try:\n    from cocoindex.connectors import surrealdb\nexcept ImportError as e:\n    if \"cocoindex[surrealdb]\" in str(e):\n        subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"cocoindex[surrealdb]\"], check=True)\n        from cocoindex.connectors import surrealdb","preventionTips":["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)."],"tags":["surrealdb","dependency","import","extras"],"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-14T11:17:12.474Z"}