influxdata/influxdb · error · PluginEnvironmentError

Virtual environment error

Error message

Virtual environment error: {0}

What it means

PluginEnvironmentError::VenvError wraps a VenvError (via #[from]) raised while creating or managing the Python virtual environment used by a plugin. The message forwards the underlying venv error, which typically describes why venv creation/activation failed.

Solutions

  1. Install python3-venv (and python3-pip) on the host so `python3 -m venv` works
  2. Delete the corrupted/partial plugin venv directory and retry setup
  3. Ensure the venv target directory is writable by the influxdb3 user
  4. Verify `python3 -m venv /tmp/testenv` works manually as the same user

Example fix

# before (Debian slim image, venv fails: ensurepip missing)
RUN apt-get install -y python3
# after
RUN apt-get install -y python3 python3-venv python3-pip
Defensive patterns

Strategy: try-catch

Validate before calling

# verify venv support before plugin setup
python3 -m venv /tmp/_venv_probe && rm -rf /tmp/_venv_probe \
  || { echo 'python3 venv unavailable (install python3-venv)'; exit 1; }

Type guard

fn is_venv_error(e: &PluginEnvironmentError) -> Option<&VenvError> {
    if let PluginEnvironmentError::VenvError(ve) = e { Some(ve) } else { None }
}

Try / catch

match env_manager.setup(plugin).await {
    Err(PluginEnvironmentError::VenvError(ve)) => {
        eprintln!("venv setup failed: {ve}; removing stale venv and retrying");
        fs::remove_dir_all(&venv_dir)?;
        env_manager.setup(plugin).await
    }
    other => other,
}

Prevention

When it happens

Trigger: Plugin environment setup calls the venv module (python -m venv) or manipulates the venv directory and the operation fails: python lacks the venv module, target directory unwritable or already exists in a bad state, or python is missing.

Common situations: Debian/Ubuntu images without python3-venv (ensurepip missing); read-only filesystem or non-writable plugin data dir; corrupted half-created venv from a prior failed run; python3 pointing to a minimal build.

Related errors

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

Appendix: source

Thrown at influxdb3_processing_engine/src/environment.rs:22

use observability_deps::tracing::debug;
use pyo3::prelude::PyAnyMethods;
use pyo3::{PyResult, Python};
use std::fmt::Debug;
use std::path::{Path, PathBuf};
use std::process::Command;
use std::sync::{Arc, OnceLock};
use thiserror::Error;

#[derive(Error, Debug)]
pub enum PluginEnvironmentError {
    #[error("Package manager not available: {0}")]
    PackageManagerNotFound(String),
    #[error("External call failed: {0}")]
    InstallationFailed(#[from] std::io::Error),
    #[error("Plugin environment management is disabled")]
    PluginEnvironmentDisabled,

    #[error("Virtual environment error: {0}")]
    VenvError(#[from] VenvError),

    #[error("Failed to list packages: {0}")]
    PackageListFailed(String),

    #[error(
        "Package installation has been disabled. Contact your administrator for more information."
    )]
    PackageInstallationDisabled,
}

pub trait PythonEnvironmentManager: Debug + Send + Sync + 'static {
    fn init_pyenv(
        &self,
        plugin_dir: Option<&Path>,
        virtual_env_location: Option<&PathBuf>,
    ) -> Result<(), PluginEnvironmentError>;
    fn install_packages(&self, packages: Vec<String>) -> Result<(), PluginEnvironmentError>;

View on GitHub (pinned to 06200ef96b)