{"record":{"id":"7095618778c65ca6","repo":"cocoindex-io/cocoindex","slug":"failed-to-load-module-app-target-e","errorCode":null,"errorMessage":"Failed to load module '{app_target}': {e}","messagePattern":"Failed to load module '(.+?)': (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"python/cocoindex/user_app_loader.py","lineNumber":106,"sourceCode":"            if app_dir in sys.path and sys.path[0] == app_dir:\n                sys.path.pop(0)\n\n    # If the target looks like a bare module name (e.g. \"main\") and a\n    # corresponding file exists in the CWD inside a package, load via the\n    # package-qualified name so relative imports work.\n    candidate_file = os.path.join(os.getcwd(), app_target + \".py\")\n    cwd = os.getcwd()\n    if os.path.isfile(candidate_file) and os.path.isfile(\n        os.path.join(cwd, \"__init__.py\")\n    ):\n        root_parent, package_parts = _find_package_root(cwd)\n        return _import_as_package_module(root_parent, package_parts, app_target)\n\n    # Try as module\n    try:\n        return importlib.import_module(app_target)\n    except ImportError as e:\n        raise Error(f\"Failed to load module '{app_target}': {e}\") from e\n    except Exception as e:\n        raise Error(f\"Unexpected error importing module '{app_target}': {e}\") from e\n","sourceCodeStart":88,"sourceCodeEnd":109,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/user_app_loader.py#L88-L109","documentation":"load_user_app() tried to resolve the app target as a bare module name via importlib.import_module and got an ImportError. This is the fallback path after file-path loading; it means no importable module with that name exists on sys.path (or importing it raised ImportError internally). CocoIndex re-raises as Error with the original message appended.","triggerScenarios":"Running e.g. `cocoindex ls main` where no `main.py`/`main` package is importable from CWD or sys.path; the module exists but one of its imports raises ImportError; sys.path lacks the app directory.","commonSituations":"Forgetting the .py extension handling assumptions, running the CLI from the wrong directory, PYTHONPATH not including the project root, or an app whose top-level `import some_lib` fails because the dependency isn't installed.","solutions":["Run the command from the directory containing the app module, or pass an explicit file path instead of a module name.","Install the missing dependency reported in the appended ImportError message (`uv pip install <pkg>`).","Set PYTHONPATH to include the project root if the module lives in a subpackage.","Check the module name for typos (e.g. `maain` vs `main`)."],"exampleFix":"# before\n$ cocoindex ls main   # ModuleNotFoundError: No module named 'main'\n\n# after\n$ cd my_app && cocoindex ls main.py","handlingStrategy":"validation","validationCode":"import importlib.util\nname = \"main\"\nassert importlib.util.find_spec(name) is not None, f\"module {name!r} not importable from CWD\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run commands from the project root or set PYTHONPATH to include it.","Prefer passing the app file path over a bare module name.","Verify dependencies are installed in the active environment before loading the app."],"tags":["python","import","module","cli"],"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"}