cocoindex-io/cocoindex · error · Error

Failed importing file '{app_path}': {e}

Error message

Failed importing file '{app_path}': {e}

What it means

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.

Source

Thrown at python/cocoindex/user_app_loader.py:86

        # load it as a proper submodule so that relative imports work.
        if os.path.isfile(os.path.join(app_dir, "__init__.py")):
            root_parent, package_parts = _find_package_root(app_dir)
            return _import_as_package_module(root_parent, package_parts, module_name)

        if app_dir not in sys.path:
            sys.path.insert(0, app_dir)
        try:
            spec = importlib.util.spec_from_file_location(module_name, app_path)
            if spec is None:
                raise ImportError(f"Could not create spec for file: {app_path}")
            module = importlib.util.module_from_spec(spec)
            sys.modules[spec.name] = module
            if spec.loader is None:
                raise ImportError(f"Could not create loader for file: {app_path}")
            spec.loader.exec_module(module)
            return module
        except (ImportError, FileNotFoundError, PermissionError) as e:
            raise Error(f"Failed importing file '{app_path}': {e}") from e
        finally:
            if app_dir in sys.path and sys.path[0] == app_dir:
                sys.path.pop(0)

    # If the target looks like a bare module name (e.g. "main") and a
    # corresponding file exists in the CWD inside a package, load via the
    # package-qualified name so relative imports work.
    candidate_file = os.path.join(os.getcwd(), app_target + ".py")
    cwd = os.getcwd()
    if os.path.isfile(candidate_file) and os.path.isfile(
        os.path.join(cwd, "__init__.py")
    ):
        root_parent, package_parts = _find_package_root(cwd)
        return _import_as_package_module(root_parent, package_parts, app_target)

    # Try as module
    try:
        return importlib.import_module(app_target)

View on GitHub (pinned to e84aa99b32)

Solutions

1. Fix the underlying ImportError: activate the correct virtualenv / `uv pip install` the missing dependency referenced at the top of the app file.
2. Verify the file path exists and is spelled correctly relative to CWD (`ls <app_path>`).
3. Check file permissions: `chmod u+r <app_path>` or run as a user with read access.
4. If importing as a plain module name works better, pass the module name (e.g. `main`) instead of the file path.

Example fix

// before
$ cocoindex ls apps/maim.py   # FileNotFoundError

// after
$ cocoindex ls apps/main.py

app_path = "apps/main.py"
assert os.path.isfile(app_path), f"app file not found: {app_path}"
assert os.access(app_path, os.R_OK), f"app file not readable: {app_path}"

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not create spec for file: {app_path}
• Could not create loader for file: {app_path}
• Failed importing '{full_module_name}' from package: {e}
• Application file path not found: {app_target}
• Failed to load module '{app_target}': {e}

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