cocoindex-io/cocoindex · error · ImportError

aiomysql is required for async Doris connections. Install it

Error message

aiomysql is required for async Doris connections. Install it with: pip install aiomysql

What it means

The async MySQL-protocol connection helper for Doris depends on the optional third-party package aiomysql. It is not a hard dependency of cocoindex, so connect_async imports it lazily and raises ImportError with install instructions when missing.

Source

Thrown at python/cocoindex/connectors/doris/_target.py:1371

# ============================================================
# Query helpers
# ============================================================


async def connect_async(
    fe_host: str,
    query_port: int = 9030,
    username: str = "root",
    password: str = "",
    database: str | None = None,
) -> Any:
    """Connect to Doris via MySQL protocol (async, using aiomysql)."""
    try:
        import aiomysql  # type: ignore
    except ImportError:
        raise ImportError(
            "aiomysql is required for async Doris connections. "
            "Install it with: pip install aiomysql"
        )
    return await aiomysql.connect(
        host=fe_host,
        port=query_port,
        user=username,
        password=password,
        db=database,
        autocommit=True,
    )


def build_vector_search_query(
    table: str,
    vector_field: str,
    query_vector: list[float],
    metric: str = "l2_distance",

View on GitHub (pinned to e84aa99b32)

Solutions

1. Install the dependency: pip install aiomysql
2. Or install the doris extra if provided: pip install 'cocoindex[doris]'
3. Alternatively use the sync connection helper if async is not required

Example fix

// before
pip install cocoindex
// after
pip install cocoindex aiomysql

import importlib.util
assert importlib.util.find_spec("aiomysql"), "pip install aiomysql"

try:
    conn = await connect_async(host, port, user, password, db)
except ImportError:
    conn = connect_sync(host, port, user, password, db)  # pymysql fallback

When it happens

Trigger: Calling connect_async (or any query path that uses it, e.g. vector search execution) in an environment where aiomysql was never installed.

Common situations: Fresh deployment/CI environment where the extras group wasn't installed; switching from sync (pymysql installed) to async usage; slim Docker images without optional deps.

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
• sqlite-vec is required for vector support. Install it with:
• surrealdb is required to use the SurrealDB connector. Please
• Batching and runner require the function to be async. Use @c
• Async functions are not supported by @coco.fn decorator when

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