cocoindex-io/cocoindex · error · ImportError

oci is required to use the Oracle Cloud Infrastructure Objec

Error message

oci is required to use the Oracle Cloud Infrastructure Object Storage source connector. Please install cocoindex[oci].

What it means

The Oracle Cloud Infrastructure Object Storage source connector optionally depends on the `oci` package. The import is wrapped in try/except at module load, and if `oci` is missing the module raises ImportError with instructions to install the cocoindex[oci] extra.

Source

Thrown at python/cocoindex/connectors/oci_object_storage/_source.py:38

    "OCIWalker",
    "get_object",
    "list_objects",
    "read",
]

import asyncio
import contextlib
import json
import logging
from collections.abc import AsyncIterable, AsyncIterator
from datetime import datetime, timedelta, timezone
from pathlib import PurePath
from typing import Any, Iterator, cast

try:
    from oci.exceptions import ServiceError  # type: ignore[import-not-found]
except ImportError as e:
    raise ImportError(
        "oci is required to use the Oracle Cloud Infrastructure Object "
        "Storage source connector. Please install cocoindex[oci]."
    ) from e

from cocoindex._internal.live_component import (
    _IMMEDIATE_READY,
    LiveMapSubscriber,
    LiveStream,
    ReadyAwaitable,
)
from cocoindex.connectorkits import SingleWatcherGuard
from cocoindex.resources import file

_logger = logging.getLogger(__name__)

_OBJECT_EVENT_PREFIX = "com.oraclecloud.objectstorage."

# Wall-clock tolerance for the event-time cutoff. Events with eventTime older

View on GitHub (pinned to e84aa99b32)

Solutions

Install the extra: pip install "cocoindex[oci]" (or uv add "cocoindex[oci]").
Install the oci package directly: pip install oci.
If OCI is not needed, remove the oci_object_storage import/usage from the pipeline.

Example fix

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

Defensive patterns

Strategy: fallback

Validate before calling

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

Try / catch

try:
    from cocoindex.connectors import oci_object_storage
except ImportError as e:
    raise SystemExit(f"OCI connector unavailable: {e}") from e

Prevention

Install optional extras for every connector you use: pip install "cocoindex[oci]".
Pin the extras in pyproject.toml/requirements so CI and prod get them.
Smoke-test imports of all connectors in CI before deployment.

When it happens

Trigger: Importing python/cocoindex/connectors/oci_object_storage/_source.py (directly or via `from cocoindex.connectors import oci_object_storage`) in an environment where the `oci` package is not installed.

Common situations: Installing cocoindex without extras (pip install cocoindex) then using the OCI connector; deploying to a container where optional dependencies were pruned.

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/8167aee402a72604. Report an issue: GitHub.