{"record":{"id":"97693f6be6d07c05","repo":"PyO3/pyo3","slug":"failed-to-import-exception","errorCode":null,"errorMessage":"failed to import exception {}.{}: {}","messagePattern":"failed to import exception (.+?)\\.(.+?): (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/impl_/exceptions.rs","lineNumber":22,"sourceCode":"    imported_value: PyOnceLock<Py<PyType>>,\n    module: &'static str,\n    name: &'static str,\n}\n\nimpl ImportedExceptionTypeObject {\n    pub const fn new(module: &'static str, name: &'static str) -> Self {\n        Self {\n            imported_value: PyOnceLock::new(),\n            module,\n            name,\n        }\n    }\n\n    pub fn get<'py>(&self, py: Python<'py>) -> &Bound<'py, PyType> {\n        self.imported_value\n            .import(py, self.module, self.name)\n            .unwrap_or_else(|e| {\n                panic!(\n                    \"failed to import exception {}.{}: {}\",\n                    self.module, self.name, e\n                )\n            })\n    }\n}\n","sourceCodeStart":4,"sourceCodeEnd":29,"githubUrl":"https://github.com/PyO3/pyo3/blob/ac9b6899d348be4d54614d060dea53a645a12e36/src/impl_/exceptions.rs#L4-L29","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Fix the embedded interpreter setup so the exception's module is importable (set PYTHONHOME/PYTHONPATH or attach stdlib)","Verify the exception module exists: `python -c \"import <module>; print(<module>.<name>)\"`","Pin/align pyo3 and Python versions so the referenced exception module/name matches"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"fn exception_module_available(py: Python<'_>, module: &str) -> bool {\n    py.import(module).is_ok()\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify each referenced exception exists on all target Python versions","Configure embedded interpreters with a complete stdlib (PYTHONHOME/PYTHONPATH)","Test imports in minimal environments (slim containers, embedded builds)"],"tags":["exceptions","import-error","embedded-python","panic"],"backgroundTag":"python-module-import-failed","analyzedSha":"ac9b6899d348be4d54614d060dea53a645a12e36","analyzedAt":"2026-09-05T09:20:35.319Z","contentChangedAt":"2026-09-05T09:20:35.319Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}