{"record":{"id":"df09d6fe0600596b","repo":"cocoindex-io/cocoindex","slug":"failed-importing-file-app-path-e","errorCode":null,"errorMessage":"Failed importing file '{app_path}': {e}","messagePattern":"Failed importing file '(.+?)': (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"python/cocoindex/user_app_loader.py","lineNumber":86,"sourceCode":"        # load it as a proper submodule so that relative imports work.\n        if os.path.isfile(os.path.join(app_dir, \"__init__.py\")):\n            root_parent, package_parts = _find_package_root(app_dir)\n            return _import_as_package_module(root_parent, package_parts, module_name)\n\n        if app_dir not in sys.path:\n            sys.path.insert(0, app_dir)\n        try:\n            spec = importlib.util.spec_from_file_location(module_name, app_path)\n            if spec is None:\n                raise ImportError(f\"Could not create spec for file: {app_path}\")\n            module = importlib.util.module_from_spec(spec)\n            sys.modules[spec.name] = module\n            if spec.loader is None:\n                raise ImportError(f\"Could not create loader for file: {app_path}\")\n            spec.loader.exec_module(module)\n            return module\n        except (ImportError, FileNotFoundError, PermissionError) as e:\n            raise Error(f\"Failed importing file '{app_path}': {e}\") from e\n        finally:\n            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)","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/user_app_loader.py#L68-L104","documentation":"load_user_app() failed while executing the Python file you passed as an app target (e.g. `cocoindex ls main.py` / app loading from a file path). During exec_module the file raised ImportError, was not found, or could not be read due to permissions; cocoindex wraps it into its Error type so the CLI reports a clear message instead of a raw traceback. It means the app entry file could not be imported, not that your app logic failed.","triggerScenarios":"Calling load_user_app with a file path whose module raises ImportError during exec (bad top-level import of an uninstalled dependency), the file does not exist at the given path, or the file is not readable by the current user (PermissionError). Also triggered when spec.loader is None for the resolved spec.","commonSituations":"Typo in the app file path; running from a directory where a venv with cocoindex deps is not activated so `import cocoindex`-adjacent deps fail inside the app file; copying an app file without its sibling modules; file owned by another user or 0600 perms.","solutions":["Fix the underlying ImportError: activate the correct virtualenv / `uv pip install` the missing dependency referenced at the top of the app file.","Verify the file path exists and is spelled correctly relative to CWD (`ls <app_path>`).","Check file permissions: `chmod u+r <app_path>` or run as a user with read access.","If importing as a plain module name works better, pass the module name (e.g. `main`) instead of the file path."],"exampleFix":"// before\n$ cocoindex ls apps/maim.py   # FileNotFoundError\n\n// after\n$ cocoindex ls apps/main.py","handlingStrategy":"validation","validationCode":"app_path = \"apps/main.py\"\nassert os.path.isfile(app_path), f\"app file not found: {app_path}\"\nassert os.access(app_path, os.R_OK), f\"app file not readable: {app_path}\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always run cocoindex CLI commands with the project's virtualenv activated.","Pass explicit, verified file paths rather than bare module names when unsure.","Keep app files free of import-time side effects that can fail in different environments."],"tags":["python","import","cli","app-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"}