cocoindex-io/cocoindex · error · ImportError

snowflake-connector-python is required to use the Snowflake

Error message

snowflake-connector-python is required to use the Snowflake connector. Please install cocoindex[snowflake].

What it means

The Snowflake connector depends on the optional `snowflake-connector-python` package. `_connect` imports it lazily; if missing, it re-raises an ImportError pointing to the `cocoindex[snowflake]` extra. The library deliberately keeps Snowflake support optional to avoid forcing heavy dependencies on all users.

Source

Thrown at python/cocoindex/connectors/snowflake/_target.py:337

        return _json_encoder(value)
    if col.encoder is not None:
        return col.encoder(value)
    return value


def _encode_row(table_schema: TableSchema[Any], row: _RowValue) -> tuple[Any, ...]:
    return tuple(
        _encode_value(col, row.get(col_name))
        for col_name, col in table_schema.columns.items()
    )


@contextmanager
def _connect(config: ConnectionConfig) -> Iterator[Any]:
    try:
        import snowflake.connector  # type: ignore[import-not-found]
    except ImportError as e:
        raise ImportError(
            "snowflake-connector-python is required to use the Snowflake connector. "
            "Please install cocoindex[snowflake]."
        ) from e

    kwargs: dict[str, str] = {
        "account": config.account,
        "user": config.user,
        "password": config.password,
    }
    if config.warehouse is not None:
        kwargs["warehouse"] = config.warehouse
    if config.role is not None:
        kwargs["role"] = config.role

    conn = snowflake.connector.connect(**kwargs)
    try:
        yield conn
    finally:

View on GitHub (pinned to e84aa99b32)

Solutions

Install the extra: `pip install 'cocoindex[snowflake]'` (or `uv add 'cocoindex[snowflake]'`).
Add cocoindex[snowflake] to requirements.txt / pyproject dependencies so environments get it automatically.
If offline, ensure snowflake-connector-python is vendored/installed from your private index.

Example fix

// before
pip install cocoindex
// after
pip install "cocoindex[snowflake]"

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec("snowflake.connector") is None:
    raise SystemExit("Install the Snowflake extra: pip install 'cocoindex[snowflake]'")

Try / catch

try:
    target = snowflake.table_target(...)
except ImportError as e:
    if "cocoindex[snowflake]" in str(e):
        raise SystemExit("Run: pip install 'cocoindex[snowflake]'") from e
    raise

Prevention

Pin extras in dependencies: cocoindex[snowflake].
Run a dependency check (importlib.util.find_spec) at app startup.
Keep CI and production images built from the same requirements file.

When it happens

Trigger: Using any Snowflake target API (table_target / applying actions, which calls `_connect`) in an environment where `snowflake-connector-python` is not installed — i.e. cocoindex installed without the [snowflake] extra.

Common situations: Fresh CI/production environments where only `pip install cocoindex` was run; deploying a pipeline that worked locally (where the extra was installed) to a slim Docker image; forgetting to update requirements after adding a Snowflake target.

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/91dba8476849eb73. Report an issue: GitHub.