cocoindex-io/cocoindex · error · ImportError

apache-iggy is required to use the Iggy connector. Please in

Error message

apache-iggy is required to use the Iggy connector. Please install cocoindex[iggy].

What it means

The Iggy source connector depends on the optional apache-iggy package. If importing IggyClient/IggyConsumer etc. fails at module import, an ImportError is raised instructing the user to install cocoindex[iggy].

Source

Thrown at python/cocoindex/connectors/iggy/_source.py:24

that carry an application-level key.
"""

from __future__ import annotations

import asyncio
import logging
from collections import deque
from datetime import timedelta
from typing import Any, Callable

try:
    from apache_iggy import AutoCommit  # type: ignore[import-not-found]
    from apache_iggy import IggyClient  # type: ignore[import-not-found]
    from apache_iggy import IggyConsumer  # type: ignore[import-not-found]
    from apache_iggy import PollingStrategy  # type: ignore[import-not-found]
    from apache_iggy import ReceiveMessage  # type: ignore[import-not-found]
except ImportError as e:
    raise ImportError(
        "apache-iggy is required to use the Iggy connector. "
        "Please install cocoindex[iggy]."
    ) from e

from cocoindex._internal.live_component import (
    _IMMEDIATE_READY,
    LiveMapSubscriber,
    LiveStream,
    LiveStreamSubscriber,
    ReadyAwaitable,
)
from cocoindex._internal.typing import StableKey
from cocoindex.connectorkits import SingleWatcherGuard

_logger = logging.getLogger(__name__)


# --- Public type aliases ---

View on GitHub (pinned to e84aa99b32)

Solutions

Install the extra: pip install 'cocoindex[iggy]'
Install the package directly: pip install apache-iggy
Add cocoindex[iggy] to project dependencies/requirements

Example fix

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

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec("apache_iggy") is None:
    raise SystemExit("Install: pip install 'cocoindex[iggy]'")

Try / catch

try:
    from cocoindex.connectors import iggy
except ImportError:
    iggy = None  # feature disabled with setup hint

Prevention

Install cocoindex[iggy] wherever Iggy connectors are used
Declare extras explicitly in pyproject/requirements
Add an import smoke test in CI for each connector in use

When it happens

Trigger: Importing cocoindex.connectors.iggy._source or using the Iggy source in an environment where cocoindex was installed without the iggy extra.

Common situations: Installing base cocoindex without extras; CI images missing optional dependencies; trying out the Iggy connector on a machine where apache-iggy was never 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/d29982f2fdb5a9e5. Report an issue: GitHub.