cocoindex-io/cocoindex · error · Error

Application file path not found: {app_target}

Error message

Application file path not found: {app_target}

What it means

Raised when the application target passed to the loader looks like a path (contains a path separator or ends in `.py`) but no file exists at that location. The loader distinguishes file-path targets from dotted module names with this heuristic and refuses to proceed for a nonexistent file.

Source

Thrown at python/cocoindex/user_app_loader.py:58

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

View on GitHub (pinned to e84aa99b32)

Solutions

  1. Run the CLI from the directory containing the app file, or pass an absolute path.
  2. Check the path for typos and confirm the file exists (`ls`/`test -f <path>`).
  3. If you meant an installed module, drop the path-like form and use the dotted module name (no `/` or `.py`).

Example fix

// before
cocoindex update ./src/main.py   # run from repo root, file is at ./app/main.py
// after
cocoindex update ./app/main.py
Defensive patterns

Strategy: validation

Validate before calling

import os
if os.sep in target or target.lower().endswith(".py"):
    assert os.path.isfile(target), f"app file not found: {os.path.abspath(target)}"

Try / catch

try:
    app = cocoindex.user_app_loader.load_user_app(app_target)
except cocoindex.Error as e:
    if 'file path not found' in str(e):
        print(f'Check the path; cwd={os.getcwd()}'); sys.exit(1)
    raise

Prevention

When it happens

Trigger: Running e.g. `cocoindex update ./main.py` or `cocoindex update app/main.py` from a directory where that file does not exist, or with a typo in the path.

Common situations: Running the CLI from the wrong working directory; typos in the filename; assuming relative paths resolve from the project root when the CLI resolves them from cwd; deleted or moved app file.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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