influxdata/influxdb · critical · VenvError

Failed to initialize virtualenv

Error message

Failed to initialize virtualenv: {0}

What it means

`VenvError::InitError` indicates the Python virtualenv failed to initialize. The processing engine lazily initializes the Python runtime once (via a `Once`); if locating/embedding the interpreter or initializing the venv fails, this error carries the underlying message.

Solutions

1. Install a compatible Python interpreter and ensure it is on the server's PATH.
2. Set the environment variable the server uses to point at the Python installation/venv explicitly.
3. Recreate the virtualenv with the Python version the server was built against and reinstall plugin dependencies.
4. Check the inner message embedded in the error for the precise initialization failure.

Example fix

// before (no python found)
$ influxdb3 run
// after
$ apt install python3.10 python3.10-venv
$ export PYTHON_HOME=/usr/bin/python3.10
$ influxdb3 run

# shell: before starting the server
command -v python3 && python3 --version  # must match the version the server was built against
[ -n "$PYTHON_HOME" ] && [ -x "$PYTHON_HOME" ] && echo ok

// Rust caller
match engine.init_python() {
    Err(VenvError::InitError(msg)) => eprintln!("venv init failed: {msg}; check Python install"),
    Err(e) => return Err(e.into()),
    Ok(()) => {},
}

When it happens

Trigger: First plugin invocation triggering `init_python`; `find_python_install()` fails to locate a Python installation, or `pyo3`'s `Python::with_embedded_interpreter`-style setup fails with an internal message that gets stringified into InitError.

Common situations: Python not installed or not on PATH in the server environment; wrong PYTHON_HOME-like env configuration; incompatible Python version (e.g. server built against 3.10 but 3.12 present); missing venv packages after deployment.

Related errors

• Error shelling out
• {0}
• At least one field is required
• CA certificate PEM should be valid
• call site contains null bytes

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

Appendix: source

Thrown at influxdb3_processing_engine/src/virtualenv.rs:13

use observability_deps::tracing::debug;
use pyo3::Python;
use std::env;
use std::ffi::CString;
use std::path::{Path, PathBuf};
use std::sync::Once;
use thiserror::Error;

static PYTHON_INIT: Once = Once::new();

#[derive(Error, Debug)]
pub enum VenvError {
    #[error("Failed to initialize virtualenv: {0}")]
    InitError(String),
    #[error("Error shelling out: {0}")]
    CommandError(#[from] std::io::Error),
}

// Find the python installation location (not virtual env).
// XXX: use build flag?
fn find_python_install() -> Option<PathBuf> {
    let influxdb3_exe = env::current_exe().unwrap();
    let influxdb3_exe_dir = influxdb3_exe.parent().unwrap();
    let influxdb3_rel_dir = influxdb3_exe_dir.join("python");
    let influxdb3_linux_dir = influxdb3_exe_dir.join("../lib/influxdb3/python");

    let python_inst = if cfg!(target_os = "linux")
        && (influxdb3_exe_dir == Path::new("/usr/bin")
            || influxdb3_exe_dir == Path::new("/usr/local/bin"))
        && influxdb3_linux_dir.is_dir()
    {

View on GitHub (pinned to 06200ef96b)