cocoindex-io/cocoindex · error · Error

Failed importing '{full_module_name}' from package: {e}

Error message

Failed importing '{full_module_name}' from package: {e}

What it means

Raised (as a cocoindex `Error`) when the user's application module could not be imported as a package member. `load_user_app` resolved the target as a module path (e.g. `mypackage.main`), inserted the package's parent on sys.path, and `importlib.import_module` raised ImportError; this wraps it with the fully-qualified module name and the underlying cause.

Source

Thrown at python/cocoindex/user_app_loader.py:46

        parent = os.path.dirname(current)
        if parent == current:  # filesystem root
            break
        current = parent
    parts.reverse()
    return current, parts


def _import_as_package_module(
    root_parent: str, package_parts: list[str], module_name: str
) -> types.ModuleType:
    """Import *module_name* as a submodule of the package described by *package_parts*."""
    full_module_name = ".".join(package_parts + [module_name])
    if root_parent not in sys.path:
        sys.path.insert(0, root_parent)
    try:
        return importlib.import_module(full_module_name)
    except ImportError as e:
        raise Error(f"Failed importing '{full_module_name}' from package: {e}") from e


def load_user_app(app_target: str) -> types.ModuleType:
    """
    Loads the user's application, which can be a file path or an installed module name.
    Exits on failure.
    """
    looks_like_path = os.sep in app_target or app_target.lower().endswith(".py")

    if looks_like_path:
        if not os.path.isfile(app_target):
            raise Error(f"Application file path not found: {app_target}")
        app_path = os.path.abspath(app_target)
        app_dir = os.path.dirname(app_path)
        # Use the file basename as the module name (e.g. main.py -> "main"). This
        # matches the bare-module CLI form (`cocoindex update main`) so memo cache
        # keys are consistent across both, and avoids triggering the user's
        # `if __name__ == "__main__":` block during module loading.

View on GitHub (pinned to e84aa99b32)

Solutions

1. Check the chained ImportError (`from e`) message for the real cause — missing module, missing dependency, or an exception in your app code.
2. Verify the dotted module path is correct and the package is installed or its parent directory is importable from your working directory.
3. Install the app package (e.g. `uv pip install -e .`) or run the CLI from the directory containing the package.
4. If the target is actually a file, pass the file path instead of a dotted module name.

Example fix

// before
cocoindex update myapp.main   # myapp not installed
// after
uv pip install -e ./myapp
cocoindex update myapp.main

import importlib.util
spec = importlib.util.find_spec("myapp.main")
if spec is None:
    raise SystemExit("module myapp.main not importable — install the package or fix the path")

try:
    app = cocoindex.user_app_loader.load_user_app(target)
except cocoindex.Error as e:
    print(f'Failed to load app: {e}\nCause: {e.__cause__}')
    sys.exit(1)

When it happens

Trigger: Running `cocoindex <cmd> some.module.name` where the module exists conceptually but the import fails: package not installed, parent dir not on sys.path, typo in module path, or an ImportError inside the module/package at import time.

Common situations: Forgetting `pip install`/`uv pip install -e .` of the app package; running the CLI from the wrong working directory; renaming modules so the dotted path no longer resolves; exceptions at import time inside the user's module (missing deps, bad env vars).

Related errors

• Failed to load module '{module_ref}'
• Failed to load module '{spec.module_ref}'
• 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/d21e43180f321d6c. Report an issue: GitHub.