PyO3/pyo3 · error

failed to import exception {}.{}: {}

Error message

failed to import exception {}.{}: {}

What it means

Lazy exception references (PyO3's exception group helpers) resolve their module.name lazily via import(). If Python can't import that exception class, get() panics with module, name, and the underlying import error.

Source

Thrown at src/impl_/exceptions.rs:22

    imported_value: PyOnceLock<Py<PyType>>,
    module: &'static str,
    name: &'static str,
}

impl ImportedExceptionTypeObject {
    pub const fn new(module: &'static str, name: &'static str) -> Self {
        Self {
            imported_value: PyOnceLock::new(),
            module,
            name,
        }
    }

    pub fn get<'py>(&self, py: Python<'py>) -> &Bound<'py, PyType> {
        self.imported_value
            .import(py, self.module, self.name)
            .unwrap_or_else(|e| {
                panic!(
                    "failed to import exception {}.{}: {}",
                    self.module, self.name, e
                )
            })
    }
}

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Fix the embedded interpreter setup so the exception's module is importable (set PYTHONHOME/PYTHONPATH or attach stdlib)
2. Verify the exception module exists: `python -c "import <module>; print(<module>.<name>)"`
3. Pin/align pyo3 and Python versions so the referenced exception module/name matches

fn exception_module_available(py: Python<'_>, module: &str) -> bool {
    py.import(module).is_ok()
}

When it happens

Trigger: Calling LazyTypeObject-like .get(py) for an exception whose module isn't importable in the current interpreter — wrong module name, feature not present (e.g. errno/asyncio exceptions in minimal builds), or embedded interpreter without stdlib.

Common situations: Embedded Python (PyO3 abi3/embedded) missing stdlib paths so `import` of the exceptions module fails; typo'd or changed module path after a Python version upgrade; stripped-down environment (e.g. no importlib paths configured).

Related errors

• Unknown Py_GIL_DISABLED value
• invalid hex encoding
• `pyo3_build_config::get()` requires a direct dependency on `
• Converting PyErr arguments failed: {}
• attempted to fetch exception but none was set

AI-assisted analysis of PyO3/pyo3@ac9b6899d3 (2026-09-05). Data as JSON: /api/errors/97693f6be6d07c05. Report an issue: GitHub.