{"record":{"id":"c2c85af75d2801e2","repo":"nautechsystems/nautilus_trader","slug":"failed-to-import-module-module-name-e-c2c85a","errorCode":null,"errorMessage":"Failed to import module {module_name}: {e}","messagePattern":"Failed to import module (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/live/src/python/node.rs","lineNumber":1179,"sourceCode":"    fn py_add_actor_from_config(&self, _py: Python, config: ImportableActorConfig) -> PyResult<()> {\n        log::debug!(\"`add_actor_from_config` with: {config:?}\");\n\n        // Extract module and class name from actor_path\n        let parts: Vec<&str> = config.actor_path.split(':').collect();\n        if parts.len() != 2 {\n            return Err(to_pyvalue_err(\n                \"actor_path must be in format 'module.path:ClassName'\",\n            ));\n        }\n        let (module_name, class_name) = (parts[0], parts[1]);\n\n        log::info!(\"Importing actor from module: {module_name} class: {class_name}\");\n\n        let (python_actor, actor_id) =\n            Python::attach(|py| -> anyhow::Result<(Py<PyAny>, ActorId)> {\n                let actor_module = py\n                    .import(module_name)\n                    .map_err(|e| anyhow::anyhow!(\"Failed to import module {module_name}: {e}\"))?;\n                let actor_class = actor_module\n                    .getattr(class_name)\n                    .map_err(|e| anyhow::anyhow!(\"Failed to get class {class_name}: {e}\"))?;\n\n                let config_instance =\n                    create_config_instance(py, &config.config_path, &config.config)?;\n\n                let python_actor = if let Some(config_obj) = config_instance.as_ref() {\n                    actor_class.call1((config_obj,))?\n                } else {\n                    actor_class.call0()?\n                };\n\n                log::debug!(\"Created Python actor instance: {python_actor:?}\");\n\n                let actor_id = prepare_python_actor(&python_actor, config_instance.as_ref())?;\n\n                Ok((python_actor.unbind(), actor_id))","sourceCodeStart":1161,"sourceCodeEnd":1197,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/live/src/python/node.rs#L1161-L1197","documentation":"Raised when the live node fails to import the Python module that should provide an actor class. `py.import(module_name)` returns a `PyErr` (typically `ModuleNotFoundError`) which is wrapped into this anyhow error including the module name and the Python exception text. Without the module, the actor class cannot be resolved and the actor is not created.","triggerScenarios":"Adding a Python actor with `module_name` that is not importable: typo in the module path, module not on `sys.path`, missing `__init__.py`, package not installed in the active environment, or an exception raised at module import time (top-level code).","commonSituations":"Running nautilus from a different working directory than the one containing the strategy package; missing `PYTHONPATH`; the module imports a dependency that is not installed; name mismatch between config `module` and the actual file/package.","solutions":["Verify the module name in the actor config matches the importable path and that the file/package exists.","Run `python -c \"import <module_name>\"` in the same interpreter/venv to reproduce the import error directly.","Add the module's parent directory to `PYTHONPATH` or install the package into the `python/.venv` environment.","Check for top-level exceptions in the module — the wrapped `e` shows whether it's `ModuleNotFoundError` vs. an error raised during import."],"exampleFix":"# before\nconfig = ImportableActorConfig(module='strats.my_actor', ...)  # not on sys.path\n# after\nexport PYTHONPATH=/path/to/project:$PYTHONPATH\n# or install the package: uv pip install -e .","handlingStrategy":"validation","validationCode":"# Before adding the actor, confirm the module imports\nimport importlib, sys\nmod = importlib.import_module(config.module)  # raises the same error early\nassert hasattr(mod, config.class_name), f\"{config.class_name} missing from {config.module}\"","typeGuard":"def actor_class_importable(module_name: str, class_name: str) -> bool:\n    try:\n        import importlib\n        return hasattr(importlib.import_module(module_name), class_name)\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    node.add_actor(actor_config)\nexcept Exception as e:\n    if e.__class__.__name__ == \"ImportExportError\" or \"Failed to import module\" in str(e):\n        logging.error(\"actor module %s not importable: check PYTHONPATH/venv\", actor_config.module)\n    else:\n        raise","preventionTips":["Run `python -c \"import <module>\"` in the same venv the node uses","Set PYTHONPATH or install strategy packages into python/.venv before starting the node","Start the node from the project root so relative package layout resolves","Keep top-level module code exception-free (no side effects that can raise on import)"],"tags":["python","import-error","module","live-node"],"backgroundTag":"module-init-failed","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}