What causes "Could not create loader for file: {app_path}" in cocoindex-io/cocoindex?

Use a standard `.py` source file as the app target.

cocoindex-io/cocoindex · error · ImportError

Could not create loader for file: {app_path}

Error message

Could not create loader for file: {app_path}

What it means

Raised (as ImportError, then wrapped as `Failed importing file ...`) when a spec was created for the app file but its `spec.loader` is None, meaning Python has a spec yet no loader capable of executing the file. Like the spec failure, it indicates the file is not a loadable Python module.

Source

Thrown at python/cocoindex/user_app_loader.py:82

        # `if __name__ == "__main__":` block during module loading.
        module_name = os.path.splitext(os.path.basename(app_path))[0]

        # If the file lives inside a package (directory has __init__.py),
        # 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)

View on GitHub (pinned to e84aa99b32)

Solutions

Use a standard `.py` source file as the app target.
Check the wrapped `Failed importing file '...': ...` message for the underlying cause.
If you intentionally use exotic loaders, load the module yourself and pass a dotted module name to cocoindex instead.

Example fix

// before
cocoindex update ./app/some.pyd   # not a Python source file
// after
cocoindex update ./app/main.py

Defensive patterns

Strategy: validation

Validate before calling

spec = importlib.util.spec_from_file_location("m", app_path)
assert spec is not None and spec.loader is not None, f"no loader for {app_path}"

Try / catch

try:
    app = cocoindex.user_app_loader.load_user_app(app_target)
except cocoindex.Error as e:
    if 'Could not create loader' in str(e):
        print(f'{app_target} has no importable loader; use a .py file'); sys.exit(1)
    raise

Prevention

Stick to plain `.py` source files as app targets.
Test your app loads with `python -c "import importlib.util,sys; ..."`-style import before wiring into cocoindex.
For exotic module formats, import the module yourself and pass its dotted name to the CLI.

When it happens

Trigger: Loading an app file whose file type maps to a spec without an executable loader (e.g. unusual extensions, namespace/namespace-package-like entries, or files Python recognizes but cannot exec via the source-file loader).

Common situations: Very rare in practice; seen with non-.py source files (e.g. `.pyc` handled differently), custom filesystem setups, or tooling that intercepts import machinery.

Related errors

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