cocoindex-io/cocoindex · error · ImportError

Could not create spec for file: {app_path}

Error message

Could not create spec for file: {app_path}

What it means

Raised (as ImportError, then wrapped as `Failed importing file ...`) when `importlib.util.spec_from_file_location` returns None for the given app file. Python could not derive an import spec — typically because the file has an unrecognized extension or the loader machinery cannot handle it.

Source

Thrown at python/cocoindex/user_app_loader.py:78

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

View on GitHub (pinned to e84aa99b32)

Solutions

  1. Rename the app file to have a `.py` extension (or pass the actual .py file).
  2. Confirm the path is a regular Python source file (`file <path>`, check extension).
  3. Inspect the wrapped `Failed importing file '...': ...` error for the underlying reason.

Example fix

// before
cocoindex update ./myapp    # extensionless Python file
// after
mv myapp myapp.py
cocoindex update ./myapp.py
Defensive patterns

Strategy: validation

Validate before calling

assert app_path.endswith(".py") and os.path.isfile(app_path), f"{app_path} is not a Python source file"

Try / catch

try:
    app = cocoindex.user_app_loader.load_user_app(app_target)
except cocoindex.Error as e:
    if 'Could not create spec' in str(e):
        print(f'{app_target} is not loadable Python source; rename to .py'); sys.exit(1)
    raise

Prevention

When it happens

Trigger: Calling `cocoindex update <path>` where the path is an existing file but not a loadable Python source file (e.g. missing `.py` extension on a Python file, extension Python cannot map to a loader, or a directory passed in a way that passes the isfile check only for odd filesystems).

Common situations: Passing extensionless script files; symlink/permission oddities; files with unusual extensions like `.pyx` or `.pyw` handled differently on some setups; passing a directory path that some shells normalized unexpectedly.

Related errors

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