cocoindex-io/cocoindex · critical · RuntimeError

Inconsistent cocoindex installation detected: - {p} Pytho

Error message

Inconsistent cocoindex installation detected:
  - {p}

Python executable: {sys.executable}
cocoindex package file: {__file__}
cocoindex._engine file: {engine_file}

This usually happens when:
  * An old 'cocoindex._engine' .pyd is still present in the
    package directory, or
  * Multiple 'cocoindex' copies exist on sys.path
    (e.g. a local checkout + an installed wheel).

 Suggested fix:
  1. Uninstall cocoindex completely:
       pip uninstall cocoindex
  2. Reinstall it cleanly:
       pip install --no-cache-dir cocoindex
  3. Ensure there is no local 'cocoindex' directory or old
     .pyd shadowing the installed package.

What it means

The package performs a sanity check at import time verifying that the loaded cocoindex._engine native module matches the installed cocoindex package. A mismatch (or a shadowing local cocoindex directory / stale .pyd) means a broken or duplicated installation, so import fails immediately with this RuntimeError containing diagnostic paths and fix instructions.

Source

Thrown at python/cocoindex/_version_check.py:45

            f"Python executable: {sys.executable}",
            f"cocoindex package file: {__file__}",
            f"cocoindex._engine file: {engine_file}",
            "",
            "This usually happens when:",
            "  * An old 'cocoindex._engine' .pyd is still present in the",
            "    package directory, or",
            "  * Multiple 'cocoindex' copies exist on sys.path",
            "    (e.g. a local checkout + an installed wheel).",
            "",
            "Suggested fix:",
            "  1. Uninstall cocoindex completely:",
            "       pip uninstall cocoindex",
            "  2. Reinstall it cleanly:",
            "       pip install --no-cache-dir cocoindex",
            "  3. Ensure there is no local 'cocoindex' directory or old",
            "     .pyd shadowing the installed package.",
        ]
        raise RuntimeError("\n".join(msg_lines))


_sanity_check_engine()
del _sanity_check_engine

View on GitHub (pinned to e84aa99b32)

Solutions

1. pip uninstall cocoindex (repeat until 'not installed'), then pip install --no-cache-dir cocoindex
2. Check python -c "import cocoindex, cocoindex._engine; print(cocoindex.__file__, cocoindex._engine.__file__)" and remove any stale _engine .so/.pyd in the package directory
3. If working in a source checkout, uninstall the wheel (or use pip install -e) so only one cocoindex exists on sys.path
4. Clear __pycache__ and rebuild native extension if installing from source (maturin develop)

Example fix

# before: import cocoindex -> RuntimeError (inconsistent installation)
pip uninstall -y cocoindex && pip install --no-cache-dir cocoindex
python -c "import cocoindex"  # succeeds

import importlib.util
spec = importlib.util.find_spec("cocoindex")
if spec and "site-packages" not in spec.origin and "dist-packages" not in spec.origin:
    print(f"WARNING: local cocoindex shadowing installed wheel: {spec.origin}")

try:
    import cocoindex
except RuntimeError as e:
    if "Inconsistent cocoindex installation" in str(e):
        print(e)  # includes step-by-step fix instructions
        raise SystemExit(1)

When it happens

Trigger: Importing cocoindex when: an old cocoindex._engine .so/.pyd remains in the package directory after an upgrade, or multiple cocoindex copies exist on sys.path (e.g. a local source checkout shadowing an installed wheel, or two wheels installed for different Python versions).

Common situations: Upgrading pip packages without uninstalling first; running code from inside a repo checkout named cocoindex while the wheel is also installed; mixing `pip install .` builds with wheel installs; stale build artifacts after `maturin develop`.

Related errors

• google-auth and google-api-python-client are required to use
• apache-iggy is required to use the Iggy connector. Please in
• apache-iggy is required to use the Iggy connector. Please in
• An app named '{name}' is already registered in this environm
• Environment settings must provide Settings.db_path (or set C

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