{"record":{"id":"387b65a31a1972e4","repo":"influxdata/influxdb","slug":"failed-to-import-plugin-module-hint-chec","errorCode":null,"errorMessage":"Failed to import plugin module '{}': {}\nHint: Check for syntax errors or missing dependencies in Python files.","messagePattern":"Failed to import plugin module '(.+?)': (.+?)\nHint: Check for syntax errors or missing dependencies in Python files\\.","errorType":"exception","errorClass":"ExecutePluginError","httpStatus":null,"severity":"error","filePath":"influxdb3_py_api/src/system_py.rs","lineNumber":373,"sourceCode":"    // A plugin dir added after FileFinder cached the parent is invisible until\n    // import caches are invalidated; retry once.\n    let import_result = match py.import(module_name) {\n        Err(e) if is_module_not_found(py, &e, module_name) => {\n            let _ = py\n                .import(\"importlib\")\n                .and_then(|m| m.call_method0(\"invalidate_caches\"));\n            py.import(module_name)\n        }\n        result => result,\n    };\n\n    // Always cleanup sys.path, even if import failed. The getattr lookup below\n    // operates on the imported module object and no longer needs sys.path.\n    let _ = sys_path.call_method1(\"pop\", (0,));\n\n    // Any import failure is the real load error and must not be masked.\n    let module = import_result.map_err(|e| {\n        ExecutePluginError::PluginError(anyhow!(\n            \"Failed to import plugin module '{}': {}\\n\\\n             Hint: Check for syntax errors or missing dependencies in Python files.\",\n            module_name,\n            e\n        ))\n    })?;\n\n    module.getattr(function_name).map_err(|e| {\n        // Only a missing attribute on the imported module means the entry-point\n        // function is absent; surface anything else as the real cause.\n        if e.is_instance_of::<PyAttributeError>(py) {\n            missing_fn_error\n        } else {\n            ExecutePluginError::PluginError(anyhow!(\n                \"Failed to load function '{}' from plugin module '{}': {}\",\n                function_name,\n                module_name,\n                e","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/influxdata/influxdb/blob/d28e26e048401c53cbb98cf2d6ab0cf1e98048ca/influxdb3_py_api/src/system_py.rs#L355-L391","documentation":"For multi-file plugins, load_function_from_module temporarily inserts the plugin directory into sys.path (under a lock) and imports the module. Any import failure — syntax error, missing dependency, bad package layout — is wrapped as ExecutePluginError::PluginError with the module name and the original Python exception text, plus the hint about syntax errors and missing dependencies. The original traceback text in '{}' is the real cause and must be read first.","triggerScenarios":"A plugin whose __init__.py or sibling module has a syntax error; imports a third-party package absent from the server's Python environment; has no/corrupt __init__.py layout; or uses Python syntax newer than the interpreter embedded in the server.","commonSituations":"Plugin developed in a personal venv then deployed to the server runtime that lacks those packages; partial uploads (a module referenced but not shipped); Python version mismatch (e.g. match statements on an older interpreter); circular imports between plugin modules.","solutions":["Read the exception text after the module name — it names the missing module or the exact syntax error","Byte-compile all plugin files before deploying: python -m py_compile plugin/__init__.py plugin/*.py","Install missing dependencies into the server's plugin Python environment, or vendor them as files inside the plugin directory","Confirm the plugin directory layout: __init__.py present, entry-point function defined, and syntax compatible with the server's Python version"],"exampleFix":"# before: __init__.py imports a package the server env lacks\nimport requests  # ModuleNotFoundError -> Failed to import plugin module\n\n# after: vendor the dependency beside the plugin or use the stdlib\nfrom plugin.vendor.requests import Session  # vendored copy shipped in the plugin dir","handlingStrategy":"try-catch","validationCode":"# deploy-time check: byte-compile every plugin file before upload\npython -m py_compile plugin/__init__.py plugin/*.py \\\n  || { echo \"plugin has syntax errors — fix before deploy\" >&2; exit 1; }","typeGuard":null,"tryCatchPattern":"match execute_plugin(/* ... */).await {\n    Err(ExecutePluginError::PluginError(e))\n        if e.to_string().contains(\"Failed to import plugin module\") =>\n    {\n        // surface the embedded Python error + hint to the plugin author verbatim\n        Err(PluginLoadRejected(e))\n    }\n    other => other,\n}","preventionTips":["Compile all plugin files (py_compile) in CI before deployment","Pin and document the plugin's dependencies; vendor them inside the plugin dir if the server env is fixed","Match the server's Python version — avoid syntax newer than its interpreter","Read the original exception after the module name in the message; it names the missing module or exact syntax error"],"tags":["influxdb","plugins","python","import-error","dependencies","multi-file-plugin"],"backgroundTag":"python-import-error","analyzedSha":"d28e26e048401c53cbb98cf2d6ab0cf1e98048ca","analyzedAt":"2026-08-16T19:53:34.623Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}