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

Module-level optional-dependency check, raised at import time of the Iggy connector. The connector depends on the third-party apache-iggy package, which is deliberately not a core dependency; importing the module without it installed raises ImportError immediately rather than failing obscurely later when IggyClient is instantiated. Fix by installing the extra: pip install 'cocoindex[iggy]'.

Source

Thrown at python/cocoindex/connectors/iggy/_target.py:18

"""
Iggy target for CocoIndex.

This module provides a two-level target state system for Iggy:
1. Topic level: Lightweight container for generation tracking (user-managed stream/topic)
2. Message level: Sends messages to the topic for upserts/deletes
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Callable, Collection, Generic, NamedTuple, Sequence

try:
    from apache_iggy import IggyClient  # type: ignore[import-not-found]
    from apache_iggy import SendMessage as Message  # 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

import cocoindex as coco
from cocoindex._internal.context_keys import ContextKey, ContextProvider
from cocoindex._internal.datatype import TypeChecker
from cocoindex._internal.target_state import AsyncTargetActionSinkFn
from cocoindex.connectorkits.fingerprint import fingerprint_bytes, fingerprint_str

# --- Type aliases ---

_MessageFingerprint = bytes

# --- Internal types ---


class _TopicKey(NamedTuple):

View on GitHub (pinned to e84aa99b32)

Solutions

1. Install the extra: pip install 'cocoindex[iggy]'
2. Install the package directly: pip install apache-iggy
3. Add cocoindex[iggy] to project dependencies

Example fix

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

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

try:
    from cocoindex.connectors.iggy import _target  # noqa
except ImportError:
    _target = None  # disable Iggy target with setup hint

When it happens

Trigger: Importing cocoindex.connectors.iggy._target or declaring an Iggy target in an environment lacking apache-iggy.

Common situations: Base cocoindex install without extras; writing/serving an app that only declared targets but never the source, so the missing extra wasn't noticed until target import.

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

• apache-iggy is required to use the Iggy connector. Please in
• google-auth and google-api-python-client are required to use
• Inconsistent cocoindex installation detected: - {p} Pytho
• Failed to load module '{module_ref}'
• Failed to load module '{spec.module_ref}'

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