{"record":{"id":"20109cae09f95b2d","repo":"cocoindex-io/cocoindex","slug":"failed-to-load-module-spec-module-ref","errorCode":null,"errorMessage":"Failed to load module '{spec.module_ref}'","messagePattern":"Failed to load module '(.+?)'","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/cli.py","lineNumber":329,"sourceCode":"    for name in sorted(persisted_names):\n        click.echo(f\"  {name}\")\n\n\ndef _load_app(app_target: str) -> App[Any, Any]:\n    \"\"\"\n    Load an app from a specifier.\n\n    Supports formats:\n        - 'path/to/app.py' - loads the only registered app\n        - 'path/to/app.py:app_name' - loads the app with 'app_name'\n        - 'path/to/app.py:app_name@env_name' - loads the app with 'app_name' in environment 'env_name'\n    \"\"\"\n    spec = _parse_app_target(app_target)\n\n    try:\n        load_user_app(spec.module_ref)\n    except UserAppLoaderError as e:\n        raise RuntimeError(f\"Failed to load module '{spec.module_ref}'\") from e\n\n    # Get target environments (filter by env_name if specified)\n    env_infos = get_registered_environment_infos()\n    if spec.env_name:\n        env_infos = [info for info in env_infos if info.env_name == spec.env_name]\n        if not env_infos:\n            raise click.ClickException(\n                f\"No environment named '{spec.env_name}' found after loading '{spec.module_ref}'.\"\n            )\n\n    # Get all apps from target environments\n    apps: list[App[Any, Any]] = []\n    for info in env_infos:\n        apps.extend(info.get_apps())\n\n    # Filter by app name if specified\n    if spec.app_name:\n        matching = [a for a in apps if a._name == spec.app_name]","sourceCodeStart":311,"sourceCodeEnd":347,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/cli.py#L311-L347","documentation":"CLI commands (show, update, drop) resolve an app target by loading its module; if load_user_app raises UserAppLoaderError, this RuntimeError is raised naming the module reference. Identical family to the `ls` loader error but for app-target commands.","triggerScenarios":"Running `cocoindex show mod:env`, `cocoindex update mod`, or `cocoindex drop mod` where the module fails to import or register apps — bad module ref, import-time exception, wrong working directory, or unregistered environment name after a successful load.","commonSituations":"Referring to an app in a module that was renamed; CI pipelines running from a different cwd; module importing secrets/env-dependent code that fails in the CLI environment.","solutions":["Verify the module imports cleanly: python -c \"import <module_ref>\" and fix the chained __cause__ error","Run the CLI from the project root or fix the module path in the app target","Install any missing dependencies used by the module","Confirm the module registers the app/Environment at import time"],"exampleFix":"// before\ncocoindex update myapp  # Failed to load module 'myapp'\n// after\ncd /project && python -c \"import myapp\"  # diagnose\npip install -r requirements.txt\ncocoindex update myapp","handlingStrategy":"try-catch","validationCode":"import importlib\ntry:\n    importlib.import_module(module_ref)\nexcept ImportError as e:\n    raise SystemExit(f\"cannot load '{module_ref}': {e}\")","typeGuard":null,"tryCatchPattern":"try:\n    app.update_blocking(...)\nexcept RuntimeError as e:\n    if str(e).startswith(\"Failed to load module\"):\n        print(f\"check module '{spec.module_ref}': {e.__cause__}\")","preventionTips":["Smoke-test `cocoindex show <module>` in CI before update/drop","Fix the working directory / module path convention across scripts","Ensure import-time dependencies are installed in the CLI environment"],"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"}