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.

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

• 0 < N <= 12
• Attaching a thread to the interpreter is currently…
• Attaching a thread to the interpreter is prohibited while a…
• attempted to fetch exception but none was set
• Cannot attach to the Python interpreter while it is…

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

Appendix: 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)