influxdata/influxdb · error · ExecutePluginError::PluginError

Failed to import plugin module

Error message

Failed to import plugin module '{module_name}': {e}
Hint: Check for syntax errors or missing dependencies in Python files.

What it means

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.

Solutions

1. Read the wrapped Python traceback in the error message — it names the exact file/line and missing module; fix that first.
2. Install missing dependencies into the Python environment used by influxdb3 (`pip install <pkg>` in the venv the server runs with).
3. Run `python -m py_compile <plugin>.py` (or import it manually in a REPL) to catch syntax/top-level errors before loading.
4. Ensure the plugin file's module-level code doesn't raise at import time (wrap side effects in functions).

Example fix

// plugin my_plugin.py — before
data = pd.read_csv("data.csv")  # raises at import if pandas missing/file absent
// after
import pandas as pd  # ensure installed: pip install pandas

def process(loader):
    data = loader()
    ...

// before loading the plugin, compile-check and check deps
import subprocess, sys
r = subprocess.run([sys.executable, "-m", "py_compile", plugin_file], capture_output=True)
if r.returncode != 0:
    raise SystemExit(f"Plugin syntax error:\n{r.stderr.decode()}")
# and verify third-party imports resolve in the target env:
for mod in ("pandas", "requests"):
    subprocess.run([sys.executable, "-c", f"import {mod}"], check=True)

try {
  loadPluginFunction(pluginDir, module, fn);
} catch (e) {
  if (String(e.message).includes("Failed to import plugin module")) {
    // surface the wrapped Python traceback and hint: syntax error or missing dependency
    console.error(e.message);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to import plugin module
• error converting the schedule time
• Failed to load function
• Invalid plugin directory name
• Invalid UTF-8 in parent directory path

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/64c3aef3e8603cdc. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_py_api/src/system_py.rs:369

    // A plugin dir added after FileFinder cached the parent is invisible until
    // import caches are invalidated; retry once.
    let import_result = match py.import(module_name) {
        Err(e) if is_module_not_found(py, &e, module_name) => {
            let _ = py
                .import("importlib")
                .and_then(|m| m.call_method0("invalidate_caches"));
            py.import(module_name)
        }
        result => result,
    };

    // Always cleanup sys.path, even if import failed. The getattr lookup below
    // operates on the imported module object and no longer needs sys.path.
    let _ = sys_path.call_method1("pop", (0,));

    // Any import failure is the real load error and must not be masked.
    let module = import_result.map_err(|e| {
        ExecutePluginError::PluginError(anyhow!(
            "Failed to import plugin module '{}': {}\n\
             Hint: Check for syntax errors or missing dependencies in Python files.",
            module_name,
            e
        ))
    })?;

    module.getattr(function_name).map_err(|e| {
        // Only a missing attribute on the imported module means the entry-point
        // function is absent; surface anything else as the real cause.
        if e.is_instance_of::<PyAttributeError>(py) {
            missing_fn_error
        } else {
            ExecutePluginError::PluginError(anyhow!(
                "Failed to load function '{}' from plugin module '{}': {}",
                function_name,
                module_name,
                e

View on GitHub (pinned to 06200ef96b)