nautechsystems/nautilus_trader · error

Failed to import module {module_name}: {e}

Error message

Failed to import module {module_name}: {e}

What it means

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.

Source

Thrown at crates/live/src/python/node.rs:1179

    fn py_add_actor_from_config(&self, _py: Python, config: ImportableActorConfig) -> PyResult<()> {
        log::debug!("`add_actor_from_config` with: {config:?}");

        // Extract module and class name from actor_path
        let parts: Vec<&str> = config.actor_path.split(':').collect();
        if parts.len() != 2 {
            return Err(to_pyvalue_err(
                "actor_path must be in format 'module.path:ClassName'",
            ));
        }
        let (module_name, class_name) = (parts[0], parts[1]);

        log::info!("Importing actor from module: {module_name} class: {class_name}");

        let (python_actor, actor_id) =
            Python::attach(|py| -> anyhow::Result<(Py<PyAny>, ActorId)> {
                let actor_module = py
                    .import(module_name)
                    .map_err(|e| anyhow::anyhow!("Failed to import module {module_name}: {e}"))?;
                let actor_class = actor_module
                    .getattr(class_name)
                    .map_err(|e| anyhow::anyhow!("Failed to get class {class_name}: {e}"))?;

                let config_instance =
                    create_config_instance(py, &config.config_path, &config.config)?;

                let python_actor = if let Some(config_obj) = config_instance.as_ref() {
                    actor_class.call1((config_obj,))?
                } else {
                    actor_class.call0()?
                };

                log::debug!("Created Python actor instance: {python_actor:?}");

                let actor_id = prepare_python_actor(&python_actor, config_instance.as_ref())?;

                Ok((python_actor.unbind(), actor_id))

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Verify the module name in the actor config matches the importable path and that the file/package exists.
  2. Run `python -c "import <module_name>"` in the same interpreter/venv to reproduce the import error directly.
  3. Add the module's parent directory to `PYTHONPATH` or install the package into the `python/.venv` environment.
  4. Check for top-level exceptions in the module — the wrapped `e` shows whether it's `ModuleNotFoundError` vs. an error raised during import.

Example fix

# before
config = ImportableActorConfig(module='strats.my_actor', ...)  # not on sys.path
# after
export PYTHONPATH=/path/to/project:$PYTHONPATH
# or install the package: uv pip install -e .
Defensive patterns

Strategy: validation

Validate before calling

# Before adding the actor, confirm the module imports
import importlib, sys
mod = importlib.import_module(config.module)  # raises the same error early
assert hasattr(mod, config.class_name), f"{config.class_name} missing from {config.module}"

Type guard

def actor_class_importable(module_name: str, class_name: str) -> bool:
    try:
        import importlib
        return hasattr(importlib.import_module(module_name), class_name)
    except ImportError:
        return False

Try / catch

try:
    node.add_actor(actor_config)
except Exception as e:
    if e.__class__.__name__ == "ImportExportError" or "Failed to import module" in str(e):
        logging.error("actor module %s not importable: check PYTHONPATH/venv", actor_config.module)
    else:
        raise

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/c2c85af75d2801e2. Report an issue: GitHub.