{"record":{"id":"1ec778c02b38a3f9","repo":"cocoindex-io/cocoindex","slug":"confluent-kafka-is-required-to-use-the-kafka-conne","errorCode":null,"errorMessage":"confluent_kafka is required to use the Kafka connector. Please install cocoindex[kafka].","messagePattern":"confluent_kafka is required to use the Kafka connector\\. Please install cocoindex\\[kafka\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/kafka/_source.py","lineNumber":24,"sourceCode":"primitive stream (with a ``payloads()`` view yielding bytes), and\n``topic_as_map`` interprets messages as a keyed map for use with ``mount_each``.\n\nUser-facing docs and worked examples:\nhttps://cocoindex.io/docs/connectors/kafka\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom collections import deque\nfrom typing import Callable\n\ntry:\n    from confluent_kafka import Message, TopicPartition  # type: ignore[import-not-found]\n    from confluent_kafka.aio import AIOConsumer  # type: ignore[import-not-found]\nexcept ImportError as e:\n    raise ImportError(\n        \"confluent_kafka is required to use the Kafka connector. \"\n        \"Please install cocoindex[kafka].\"\n    ) from e\n\nfrom cocoindex._internal.live_component import (\n    _IMMEDIATE_READY,\n    LiveMapSubscriber,\n    LiveStream,\n    LiveStreamSubscriber,\n    ReadyAwaitable,\n)\nfrom cocoindex._internal.typing import StableKey\nfrom cocoindex.connectorkits import SingleWatcherGuard\n\n_logger = logging.getLogger(__name__)\n\n\n# --- Public type aliases ---","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/kafka/_source.py#L6-L42","documentation":"Importing the Kafka source connector module fails because the optional third-party package confluent_kafka is not installed. CocoIndex keeps the Kafka connector optional so the core install stays light; importing the module without the dependency raises ImportError with an actionable message pointing to the 'kafka' extra.","triggerScenarios":"Any import of python/cocoindex/connectors/kafka/_source.py (directly or via the kafka connectors package __init__) when `from confluent_kafka import Message, TopicPartition` or `from confluent_kafka.aio import AIOConsumer` raises ImportError, i.e. confluent_kafka is absent or broken.","commonSituations":"Installing cocoindex without the [kafka] extra then importing the Kafka source connector; a slim/production Docker image that omitted extras; confluent_kafka failing to build (missing librdkafka) so the import fails even though installed.","solutions":["Install the extra: `pip install 'cocoindex[kafka]'` (or `uv add 'cocoindex[kafka]'`).","If already installed, verify `python -c \"import confluent_kafka\"` works; reinstall or fix librdkafka if it errors.","Add the extra to your project dependency file (pyproject.toml) so environments are reproducible."],"exampleFix":"// before\nfrom cocoindex.connectors.kafka import KafkaSource  # ImportError at import time\n// after\n# pip install 'cocoindex[kafka]'\nfrom cocoindex.connectors.kafka import KafkaSource","handlingStrategy":"try-catch","validationCode":"try:\n    import confluent_kafka  # noqa: F401\n    from confluent_kafka.aio import AIOConsumer  # noqa: F401\nexcept ImportError:\n    raise SystemExit(\"Install the Kafka extra: pip install 'cocoindex[kafka]'\")","typeGuard":null,"tryCatchPattern":"try:\n    from cocoindex.connectors.kafka import KafkaSource\nexcept ImportError as e:\n    if \"confluent_kafka\" in str(e):\n        raise SystemExit(\"Install: pip install 'cocoindex[kafka]'\") from e\n    raise","preventionTips":["Always install optional connectors via extras: cocoindex[kafka].","Declare the extra in pyproject.toml dependencies.","Smoke-test imports in CI with the same extras you deploy."],"tags":["python","kafka","optional-dependency","import-error"],"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-14T05:17:10.506Z"}