{"record":{"id":"d21e43180f321d6c","repo":"cocoindex-io/cocoindex","slug":"failed-importing-full-module-name-from-package","errorCode":null,"errorMessage":"Failed importing '{full_module_name}' from package: {e}","messagePattern":"Failed importing '(.+?)' from package: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"python/cocoindex/user_app_loader.py","lineNumber":46,"sourceCode":"        parent = os.path.dirname(current)\n        if parent == current:  # filesystem root\n            break\n        current = parent\n    parts.reverse()\n    return current, parts\n\n\ndef _import_as_package_module(\n    root_parent: str, package_parts: list[str], module_name: str\n) -> types.ModuleType:\n    \"\"\"Import *module_name* as a submodule of the package described by *package_parts*.\"\"\"\n    full_module_name = \".\".join(package_parts + [module_name])\n    if root_parent not in sys.path:\n        sys.path.insert(0, root_parent)\n    try:\n        return importlib.import_module(full_module_name)\n    except ImportError as e:\n        raise Error(f\"Failed importing '{full_module_name}' from package: {e}\") from e\n\n\ndef load_user_app(app_target: str) -> types.ModuleType:\n    \"\"\"\n    Loads the user's application, which can be a file path or an installed module name.\n    Exits on failure.\n    \"\"\"\n    looks_like_path = os.sep in app_target or app_target.lower().endswith(\".py\")\n\n    if looks_like_path:\n        if not os.path.isfile(app_target):\n            raise Error(f\"Application file path not found: {app_target}\")\n        app_path = os.path.abspath(app_target)\n        app_dir = os.path.dirname(app_path)\n        # Use the file basename as the module name (e.g. main.py -> \"main\"). This\n        # matches the bare-module CLI form (`cocoindex update main`) so memo cache\n        # keys are consistent across both, and avoids triggering the user's\n        # `if __name__ == \"__main__\":` block during module loading.","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/user_app_loader.py#L28-L64","documentation":"Raised (as a cocoindex `Error`) when the user's application module could not be imported as a package member. `load_user_app` resolved the target as a module path (e.g. `mypackage.main`), inserted the package's parent on sys.path, and `importlib.import_module` raised ImportError; this wraps it with the fully-qualified module name and the underlying cause.","triggerScenarios":"Running `cocoindex <cmd> some.module.name` where the module exists conceptually but the import fails: package not installed, parent dir not on sys.path, typo in module path, or an ImportError inside the module/package at import time.","commonSituations":"Forgetting `pip install`/`uv pip install -e .` of the app package; running the CLI from the wrong working directory; renaming modules so the dotted path no longer resolves; exceptions at import time inside the user's module (missing deps, bad env vars).","solutions":["Check the chained ImportError (`from e`) message for the real cause — missing module, missing dependency, or an exception in your app code.","Verify the dotted module path is correct and the package is installed or its parent directory is importable from your working directory.","Install the app package (e.g. `uv pip install -e .`) or run the CLI from the directory containing the package.","If the target is actually a file, pass the file path instead of a dotted module name."],"exampleFix":"// before\ncocoindex update myapp.main   # myapp not installed\n// after\nuv pip install -e ./myapp\ncocoindex update myapp.main","handlingStrategy":"validation","validationCode":"import importlib.util\nspec = importlib.util.find_spec(\"myapp.main\")\nif spec is None:\n    raise SystemExit(\"module myapp.main not importable — install the package or fix the path\")","typeGuard":null,"tryCatchPattern":"try:\n    app = cocoindex.user_app_loader.load_user_app(target)\nexcept cocoindex.Error as e:\n    print(f'Failed to load app: {e}\\nCause: {e.__cause__}')\n    sys.exit(1)","preventionTips":["Install your app package (editable install) before invoking the CLI.","Run CLI commands from the package's parent directory.","Keep the app module import-clean: no top-level code that raises on missing env/deps."],"tags":["python","import","cli","module-loading"],"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"}