{"record":{"id":"e77fd0ef76257f6c","repo":"cocoindex-io/cocoindex","slug":"failed-to-load-module-module-ref","errorCode":null,"errorMessage":"Failed to load module '{module_ref}'","messagePattern":"Failed to load module '(.+?)'","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/cli.py","lineNumber":232,"sourceCode":") -> bool:\n    \"\"\"Print a group of apps under an environment. Returns True if any app is not persisted.\"\"\"\n    has_missing = False\n    click.echo(_format_env_header(env_name, db_path))\n    for app in sorted(apps, key=lambda a: a._name):\n        if app._name in persisted_names:\n            click.echo(f\"  {app._name}\")\n        else:\n            click.echo(f\"  {app._name} [+]\")\n            has_missing = True\n    return has_missing\n\n\nasync def _ls_from_module_async(module_ref: str) -> None:\n    \"\"\"List apps from a loaded module, grouped by environment. Uses async env access so CLI never starts the background loop.\"\"\"\n    try:\n        load_user_app(module_ref)\n    except UserAppLoaderError as e:\n        raise RuntimeError(f\"Failed to load module '{module_ref}'\") from e\n\n    try:\n        env_infos = get_registered_environment_infos()\n        if not env_infos:\n            click.echo(f\"No apps are defined in '{module_ref}'.\")\n            return\n\n        # Sort: explicit environments first (by name), default environment last\n        def sort_key(info: EnvironmentInfo) -> tuple[int, str]:\n            env = info.env\n            if env is default_env_lazy():\n                return (1, \"\")\n            return (0, info.env_name or \"\")\n\n        sorted_infos = sorted(env_infos, key=sort_key)\n\n        has_missing = False\n        first_group = True","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/cli.py#L214-L250","documentation":"The `cocoindex ls` CLI loads the user's app module to discover registered apps; if the module fails to import/register (UserAppLoaderError), the loader wraps it in this RuntimeError naming the module. The original loader error is chained as __cause__.","triggerScenarios":"Running `cocoindex ls mymodule` where mymodule cannot be imported — wrong module path, ImportError inside the module, module doesn't call Environment/App registration code, or missing dependencies imported by the module.","commonSituations":"Typo in module reference (dots vs file path); running from the wrong working directory so the module isn't importable; the app file raising on import due to missing env vars or packages.","solutions":["Run the CLI from the directory containing the module, or pass the correct dotted module path (e.g. myapp.main)","Import the module directly with python -c \"import mymodule\" to see the underlying error","Install missing dependencies the module imports","Ensure the module actually defines and registers cocoindex apps at import time"],"exampleFix":"# before\ncocoindex ls my_app  # Failed to load module\n// after\ncd /path/to/project\ncocoindex ls my_app.main  # or fix import error first","handlingStrategy":"try-catch","validationCode":"import importlib\ntry:\n    importlib.import_module(\"my_app\")\nexcept ImportError as e:\n    raise SystemExit(f\"module not importable: {e}\")","typeGuard":null,"tryCatchPattern":"try:\n    result = subprocess.run([\"cocoindex\", \"ls\", module], capture_output=True)\nexcept RuntimeError as e:\n    print(f\"{e}; cause: {e.__cause__}\")","preventionTips":["Run the CLI from the project root","Verify the module imports cleanly with python -c before invoking CLI","Keep app registration code at module import time, free of side effects that fail in CLI context"],"tags":["cli","module-loading","import"],"backgroundTag":"module-init-failed","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}