{"record":{"id":"ef7d5a01d73e30e1","repo":"cocoindex-io/cocoindex","slug":"unexpected-error-importing-module-app-target","errorCode":null,"errorMessage":"Unexpected error importing module '{app_target}': {e}","messagePattern":"Unexpected error importing module '(.+?)': (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"python/cocoindex/user_app_loader.py","lineNumber":108,"sourceCode":"\n    # If the target looks like a bare module name (e.g. \"main\") and a\n    # corresponding file exists in the CWD inside a package, load via the\n    # package-qualified name so relative imports work.\n    candidate_file = os.path.join(os.getcwd(), app_target + \".py\")\n    cwd = os.getcwd()\n    if os.path.isfile(candidate_file) and os.path.isfile(\n        os.path.join(cwd, \"__init__.py\")\n    ):\n        root_parent, package_parts = _find_package_root(cwd)\n        return _import_as_package_module(root_parent, package_parts, app_target)\n\n    # Try as module\n    try:\n        return importlib.import_module(app_target)\n    except ImportError as e:\n        raise Error(f\"Failed to load module '{app_target}': {e}\") from e\n    except Exception as e:\n        raise Error(f\"Unexpected error importing module '{app_target}': {e}\") from e\n","sourceCodeStart":90,"sourceCodeEnd":109,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/user_app_loader.py#L90-L109","documentation":"While importing the app target as a module, an exception other than ImportError escaped importlib.import_module (e.g. SyntaxError, AttributeError, TypeError raised at module top level). CocoIndex labels it 'Unexpected error' to distinguish genuine code failures from import-resolution failures, and wraps it in Error.","triggerScenarios":"importlib.import_module(app_target) executes the module's top-level code and that code raises any non-ImportError exception: SyntaxError in the app file, a NameError/TypeError during initialization, or an unrelated exception from an imported library.","commonSituations":"Recently edited app file with a syntax error; top-level code that reads env vars or connects to a database and fails; Python version mismatch causing TypeError on new syntax (e.g. match statements on old interpreters).","solutions":["Read the wrapped exception message and fix the bug at the reported line in the app module.","Run `python -c \"import <module>\"` (or `python <file>.py`) directly to see the full traceback.","Check Python version compatibility (`python --version`) if the error involves new syntax.","Move heavy top-level side effects (network/DB) inside functions so import succeeds."],"exampleFix":"# before (app.py)\nDB = connect(os.environ[\"DB_URL\"])  # KeyError at import\n\n# after\ndef get_db():\n    return connect(os.environ[\"DB_URL\"])","handlingStrategy":"try-catch","validationCode":"// smoke-test import first\n// python -c \"import main\"","typeGuard":null,"tryCatchPattern":"try:\n    load_user_app(target)\nexcept Error as e:\n    print(e)  # message includes the original non-ImportError exception\n    raise SystemExit(1)","preventionTips":["Import your app module in CI (`python -c 'import app'`) to catch syntax/init errors early.","Keep module top-level code minimal; defer I/O and env-dependent work into functions.","Pin the Python version used by the app to avoid syntax incompatibilities."],"tags":["python","import","runtime-error","cli"],"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"}