cocoindex-io/cocoindex · error · RuntimeError

Failed to load module '{spec.module_ref}'

Error message

Failed to load module '{spec.module_ref}'

What it means

CLI commands (show, update, drop) resolve an app target by loading its module; if load_user_app raises UserAppLoaderError, this RuntimeError is raised naming the module reference. Identical family to the `ls` loader error but for app-target commands.

Source

Thrown at python/cocoindex/cli.py:329

    for name in sorted(persisted_names):
        click.echo(f"  {name}")


def _load_app(app_target: str) -> App[Any, Any]:
    """
    Load an app from a specifier.

    Supports formats:
        - 'path/to/app.py' - loads the only registered app
        - 'path/to/app.py:app_name' - loads the app with 'app_name'
        - 'path/to/app.py:app_name@env_name' - loads the app with 'app_name' in environment 'env_name'
    """
    spec = _parse_app_target(app_target)

    try:
        load_user_app(spec.module_ref)
    except UserAppLoaderError as e:
        raise RuntimeError(f"Failed to load module '{spec.module_ref}'") from e

    # Get target environments (filter by env_name if specified)
    env_infos = get_registered_environment_infos()
    if spec.env_name:
        env_infos = [info for info in env_infos if info.env_name == spec.env_name]
        if not env_infos:
            raise click.ClickException(
                f"No environment named '{spec.env_name}' found after loading '{spec.module_ref}'."
            )

    # Get all apps from target environments
    apps: list[App[Any, Any]] = []
    for info in env_infos:
        apps.extend(info.get_apps())

    # Filter by app name if specified
    if spec.app_name:
        matching = [a for a in apps if a._name == spec.app_name]

View on GitHub (pinned to e84aa99b32)

Solutions

1. Verify the module imports cleanly: python -c "import <module_ref>" and fix the chained __cause__ error
2. Run the CLI from the project root or fix the module path in the app target
3. Install any missing dependencies used by the module
4. Confirm the module registers the app/Environment at import time

Example fix

// before
cocoindex update myapp  # Failed to load module 'myapp'
// after
cd /project && python -c "import myapp"  # diagnose
pip install -r requirements.txt
cocoindex update myapp

import importlib
try:
    importlib.import_module(module_ref)
except ImportError as e:
    raise SystemExit(f"cannot load '{module_ref}': {e}")

try:
    app.update_blocking(...)
except RuntimeError as e:
    if str(e).startswith("Failed to load module"):
        print(f"check module '{spec.module_ref}': {e.__cause__}")

When it happens

Trigger: Running `cocoindex show mod:env`, `cocoindex update mod`, or `cocoindex drop mod` where the module fails to import or register apps — bad module ref, import-time exception, wrong working directory, or unregistered environment name after a successful load.

Common situations: Referring to an app in a module that was renamed; CI pipelines running from a different cwd; module importing secrets/env-dependent code that fails in the CLI environment.

Related errors

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

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