{"record":{"id":"32e37cd41746e491","repo":"cocoindex-io/cocoindex","slug":"inconsistent-cocoindex-installation-detected","errorCode":null,"errorMessage":"Inconsistent cocoindex installation detected:\n  - {p}\n\nPython executable: {sys.executable}\ncocoindex package file: {__file__}\ncocoindex._engine file: {engine_file}\n\nThis usually happens when:\n  * An old 'cocoindex._engine' .pyd is still present in the\n    package directory, or\n  * Multiple 'cocoindex' copies exist on sys.path\n    (e.g. a local checkout + an installed wheel).\n\n Suggested fix:\n  1. Uninstall cocoindex completely:\n       pip uninstall cocoindex\n  2. Reinstall it cleanly:\n       pip install --no-cache-dir cocoindex\n  3. Ensure there is no local 'cocoindex' directory or old\n     .pyd shadowing the installed package.","messagePattern":"Inconsistent cocoindex installation detected:\n  - \\{p\\}\n\nPython executable: \\{sys\\.executable\\}\ncocoindex package file: \\{__file__\\}\ncocoindex\\._engine file: \\{engine_file\\}\n\nThis usually happens when:\n  \\* An old 'cocoindex\\._engine' \\.pyd is still present in the\n    package directory, or\n  \\* Multiple 'cocoindex' copies exist on sys\\.path\n    \\(e\\.g\\. a local checkout \\+ an installed wheel\\)\\.\n\n Suggested fix:\n  1\\. Uninstall cocoindex completely:\n       pip uninstall cocoindex\n  2\\. Reinstall it cleanly:\n       pip install --no-cache-dir cocoindex\n  3\\. Ensure there is no local 'cocoindex' directory or old\n     \\.pyd shadowing the installed package\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/cocoindex/_version_check.py","lineNumber":45,"sourceCode":"            f\"Python executable: {sys.executable}\",\n            f\"cocoindex package file: {__file__}\",\n            f\"cocoindex._engine file: {engine_file}\",\n            \"\",\n            \"This usually happens when:\",\n            \"  * An old 'cocoindex._engine' .pyd is still present in the\",\n            \"    package directory, or\",\n            \"  * Multiple 'cocoindex' copies exist on sys.path\",\n            \"    (e.g. a local checkout + an installed wheel).\",\n            \"\",\n            \"Suggested fix:\",\n            \"  1. Uninstall cocoindex completely:\",\n            \"       pip uninstall cocoindex\",\n            \"  2. Reinstall it cleanly:\",\n            \"       pip install --no-cache-dir cocoindex\",\n            \"  3. Ensure there is no local 'cocoindex' directory or old\",\n            \"     .pyd shadowing the installed package.\",\n        ]\n        raise RuntimeError(\"\\n\".join(msg_lines))\n\n\n_sanity_check_engine()\ndel _sanity_check_engine\n","sourceCodeStart":27,"sourceCodeEnd":50,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/_version_check.py#L27-L50","documentation":"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.","triggerScenarios":"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).","commonSituations":"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`.","solutions":["pip uninstall cocoindex (repeat until 'not installed'), then pip install --no-cache-dir cocoindex","Check python -c \"import cocoindex, cocoindex._engine; print(cocoindex.__file__, cocoindex._engine.__file__)\" and remove any stale _engine .so/.pyd in the package directory","If working in a source checkout, uninstall the wheel (or use pip install -e) so only one cocoindex exists on sys.path","Clear __pycache__ and rebuild native extension if installing from source (maturin develop)"],"exampleFix":"# before: import cocoindex -> RuntimeError (inconsistent installation)\npip uninstall -y cocoindex && pip install --no-cache-dir cocoindex\npython -c \"import cocoindex\"  # succeeds","handlingStrategy":"try-catch","validationCode":"import importlib.util\nspec = importlib.util.find_spec(\"cocoindex\")\nif spec and \"site-packages\" not in spec.origin and \"dist-packages\" not in spec.origin:\n    print(f\"WARNING: local cocoindex shadowing installed wheel: {spec.origin}\")","typeGuard":null,"tryCatchPattern":"try:\n    import cocoindex\nexcept RuntimeError as e:\n    if \"Inconsistent cocoindex installation\" in str(e):\n        print(e)  # includes step-by-step fix instructions\n        raise SystemExit(1)","preventionTips":["Don't name your project directory 'cocoindex'","After upgrades, verify only one cocoindex exists: pip show cocoindex and check sys.path","Use virtualenvs per project; avoid mixing maturin develop builds with wheel installs"],"tags":["installation","import","environment","packaging"],"backgroundTag":"module-init-failed","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"}