{"record":{"id":"719ae75ffebb848d","repo":"influxdata/influxdb","slug":"failed-to-initialize-virtualenv-0","errorCode":null,"errorMessage":"Failed to initialize virtualenv: {0}","messagePattern":"Failed to initialize virtualenv: (.+?)","errorType":"exception","errorClass":"VenvError","httpStatus":null,"severity":"critical","filePath":"influxdb3_processing_engine/src/virtualenv.rs","lineNumber":13,"sourceCode":"use observability_deps::tracing::debug;\nuse pyo3::Python;\nuse std::env;\nuse std::ffi::CString;\nuse std::path::{Path, PathBuf};\nuse std::sync::Once;\nuse thiserror::Error;\n\nstatic PYTHON_INIT: Once = Once::new();\n\n#[derive(Error, Debug)]\npub enum VenvError {\n    #[error(\"Failed to initialize virtualenv: {0}\")]\n    InitError(String),\n    #[error(\"Error shelling out: {0}\")]\n    CommandError(#[from] std::io::Error),\n}\n\n// Find the python installation location (not virtual env).\n// XXX: use build flag?\nfn find_python_install() -> Option<PathBuf> {\n    let influxdb3_exe = env::current_exe().unwrap();\n    let influxdb3_exe_dir = influxdb3_exe.parent().unwrap();\n    let influxdb3_rel_dir = influxdb3_exe_dir.join(\"python\");\n    let influxdb3_linux_dir = influxdb3_exe_dir.join(\"../lib/influxdb3/python\");\n\n    let python_inst = if cfg!(target_os = \"linux\")\n        && (influxdb3_exe_dir == Path::new(\"/usr/bin\")\n            || influxdb3_exe_dir == Path::new(\"/usr/local/bin\"))\n        && influxdb3_linux_dir.is_dir()\n    {","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_processing_engine/src/virtualenv.rs#L1-L31","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install a compatible Python interpreter and ensure it is on the server's PATH.","Set the environment variable the server uses to point at the Python installation/venv explicitly.","Recreate the virtualenv with the Python version the server was built against and reinstall plugin dependencies.","Check the inner message embedded in the error for the precise initialization failure."],"exampleFix":"// before (no python found)\n$ influxdb3 run\n// after\n$ apt install python3.10 python3.10-venv\n$ export PYTHON_HOME=/usr/bin/python3.10\n$ influxdb3 run","handlingStrategy":"try-catch","validationCode":"# shell: before starting the server\ncommand -v python3 && python3 --version  # must match the version the server was built against\n[ -n \"$PYTHON_HOME\" ] && [ -x \"$PYTHON_HOME\" ] && echo ok","typeGuard":null,"tryCatchPattern":"// Rust caller\nmatch engine.init_python() {\n    Err(VenvError::InitError(msg)) => eprintln!(\"venv init failed: {msg}; check Python install\"),\n    Err(e) => return Err(e.into()),\n    Ok(()) => {},\n}","preventionTips":["Pin the Python version in deployment images to the one the server was built against","Verify Python availability in startup health checks","Rebuild the venv after interpreter upgrades"],"tags":["python","virtualenv","initialization","environment"],"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"}