{"record":{"id":"64c3aef3e8603cdc","repo":"influxdata/influxdb","slug":"failed-to-import-plugin-module-module-name-e-hint-check-for","errorCode":null,"errorMessage":"Failed to import plugin module '{module_name}': {e}\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":"error_code","errorClass":"ExecutePluginError::PluginError","httpStatus":null,"severity":"error","filePath":"influxdb3_py_api/src/system_py.rs","lineNumber":369,"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":351,"sourceCodeEnd":387,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_py_api/src/system_py.rs#L351-L387","documentation":"Thrown when `import` of the plugin module inside Python fails. The error wraps the original Python exception (e) and appends a hint pointing at syntax errors or missing dependencies, because a Python ImportError/SyntaxError during plugin import makes the plugin unloadable.","triggerScenarios":"load_plugin_function calls load_function_from_module; `py.import(module_name)` (or PyModule import) raises because the plugin .py file has a syntax error, an import of a third-party package that is not installed in the Python environment, an exception at module top-level, or a circular import.","commonSituations":"Plugin code imports pandas/requests/etc. not installed in the embedded interpreter; a typo in the plugin file (NameError at import time, e.g. calling an undefined helper at top level); Python file saved with a syntax error after a hot edit; plugin directory on sys.path shadows a stdlib module name.","solutions":["Read the wrapped Python traceback in the error message — it names the exact file/line and missing module; fix that first.","Install missing dependencies into the Python environment used by influxdb3 (`pip install <pkg>` in the venv the server runs with).","Run `python -m py_compile <plugin>.py` (or import it manually in a REPL) to catch syntax/top-level errors before loading.","Ensure the plugin file's module-level code doesn't raise at import time (wrap side effects in functions)."],"exampleFix":"// plugin my_plugin.py — before\ndata = pd.read_csv(\"data.csv\")  # raises at import if pandas missing/file absent\n// after\nimport pandas as pd  # ensure installed: pip install pandas\n\ndef process(loader):\n    data = loader()\n    ...","handlingStrategy":"try-catch","validationCode":"// before loading the plugin, compile-check and check deps\nimport subprocess, sys\nr = subprocess.run([sys.executable, \"-m\", \"py_compile\", plugin_file], capture_output=True)\nif r.returncode != 0:\n    raise SystemExit(f\"Plugin syntax error:\\n{r.stderr.decode()}\")\n# and verify third-party imports resolve in the target env:\nfor mod in (\"pandas\", \"requests\"):\n    subprocess.run([sys.executable, \"-c\", f\"import {mod}\"], check=True)","typeGuard":null,"tryCatchPattern":"try {\n  loadPluginFunction(pluginDir, module, fn);\n} catch (e) {\n  if (String(e.message).includes(\"Failed to import plugin module\")) {\n    // surface the wrapped Python traceback and hint: syntax error or missing dependency\n    console.error(e.message);\n  } else throw e;\n}","preventionTips":["py_compile every plugin file in CI before deployment.","Pin and install plugin dependencies in the same venv the server's embedded Python uses.","Keep module import side-effect free so import never raises at runtime.","Never name a plugin module the same as a stdlib/third-party module (shadowing)."],"tags":["python-plugins","import-error","module-init-failed","dependencies"],"backgroundTag":"module-init-failed","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}