{"record":{"id":"a3f0ff60866864d3","repo":"influxdata/influxdb","slug":"virtual-environment-error-0","errorCode":null,"errorMessage":"Virtual environment error: {0}","messagePattern":"Virtual environment error: (.+?)","errorType":"exception","errorClass":"PluginEnvironmentError","httpStatus":null,"severity":"error","filePath":"influxdb3_processing_engine/src/environment.rs","lineNumber":22,"sourceCode":"use observability_deps::tracing::debug;\nuse pyo3::prelude::PyAnyMethods;\nuse pyo3::{PyResult, Python};\nuse std::fmt::Debug;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse std::sync::{Arc, OnceLock};\nuse thiserror::Error;\n\n#[derive(Error, Debug)]\npub enum PluginEnvironmentError {\n    #[error(\"Package manager not available: {0}\")]\n    PackageManagerNotFound(String),\n    #[error(\"External call failed: {0}\")]\n    InstallationFailed(#[from] std::io::Error),\n    #[error(\"Plugin environment management is disabled\")]\n    PluginEnvironmentDisabled,\n\n    #[error(\"Virtual environment error: {0}\")]\n    VenvError(#[from] VenvError),\n\n    #[error(\"Failed to list packages: {0}\")]\n    PackageListFailed(String),\n\n    #[error(\n        \"Package installation has been disabled. Contact your administrator for more information.\"\n    )]\n    PackageInstallationDisabled,\n}\n\npub trait PythonEnvironmentManager: Debug + Send + Sync + 'static {\n    fn init_pyenv(\n        &self,\n        plugin_dir: Option<&Path>,\n        virtual_env_location: Option<&PathBuf>,\n    ) -> Result<(), PluginEnvironmentError>;\n    fn install_packages(&self, packages: Vec<String>) -> Result<(), PluginEnvironmentError>;","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_processing_engine/src/environment.rs#L4-L40","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install python3-venv (and python3-pip) on the host so `python3 -m venv` works","Delete the corrupted/partial plugin venv directory and retry setup","Ensure the venv target directory is writable by the influxdb3 user","Verify `python3 -m venv /tmp/testenv` works manually as the same user"],"exampleFix":"# before (Debian slim image, venv fails: ensurepip missing)\nRUN apt-get install -y python3\n# after\nRUN apt-get install -y python3 python3-venv python3-pip","handlingStrategy":"try-catch","validationCode":"# verify venv support before plugin setup\npython3 -m venv /tmp/_venv_probe && rm -rf /tmp/_venv_probe \\\n  || { echo 'python3 venv unavailable (install python3-venv)'; exit 1; }","typeGuard":"fn is_venv_error(e: &PluginEnvironmentError) -> Option<&VenvError> {\n    if let PluginEnvironmentError::VenvError(ve) = e { Some(ve) } else { None }\n}","tryCatchPattern":"match env_manager.setup(plugin).await {\n    Err(PluginEnvironmentError::VenvError(ve)) => {\n        eprintln!(\"venv setup failed: {ve}; removing stale venv and retrying\");\n        fs::remove_dir_all(&venv_dir)?;\n        env_manager.setup(plugin).await\n    }\n    other => other,\n}","preventionTips":["Install python3-venv/python3-pip on hosts running plugins","Clean up stale or partially created venv directories before retries","Ensure the venv parent directory is writable by the service user","Smoke-test `python3 -m venv` in deployment health checks"],"tags":["rust","python","venv","plugin-environment"],"backgroundTag":"venv-creation-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"}