What causes "Failed to load module '{app_target}': {e}" in cocoindex-io/cocoindex?

Run the command from the directory containing the app module, or pass an explicit file path instead of a module name.

cocoindex-io/cocoindex · error · Error

Failed to load module '{app_target}': {e}

Error message

Failed to load module '{app_target}': {e}

What it means

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.

Source

Thrown at python/cocoindex/user_app_loader.py:106

            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)
    except ImportError as e:
        raise Error(f"Failed to load module '{app_target}': {e}") from e
    except Exception as e:
        raise Error(f"Unexpected error importing module '{app_target}': {e}") from e

View on GitHub (pinned to e84aa99b32)

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`).

Example fix

# before
$ cocoindex ls main   # ModuleNotFoundError: No module named 'main'

# after
$ cd my_app && cocoindex ls main.py

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
name = "main"
assert importlib.util.find_spec(name) is not None, f"module {name!r} not importable from CWD"

Prevention

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.

When it happens

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

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

Related errors

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