What causes "Failed to import config module {config_module_name}: {e}" in nautechsystems/nautilus_trader?

Verify the full `module:Class` config path is correct and importable

Failed to import config module {config_module_name}: {e}

Error message

Failed to import config module {config_module_name}: {e}

What it means

Raised by `create_config_instance` when the module containing the config class (e.g. `MyActorConfig`) cannot be imported while building a config object for a Python actor or strategy from a serialized config path. The Python import failed, usually because the module does not exist or raised on import.

Source

Thrown at crates/system/src/python/registration.rs:579

    let Some((config_module_name, config_class_name)) = config_path.split_once(':') else {
        anyhow::bail!("config_path must be in format 'module.path:ClassName', was {config_path}");
    };

    if config_module_name.is_empty()
        || config_class_name.is_empty()
        || config_class_name.contains(':')
    {
        anyhow::bail!("config_path must be in format 'module.path:ClassName', was {config_path}");
    }

    log::debug!(
        "Importing config class from module: {config_module_name} class: {config_class_name}"
    );

    let config_module = py
        .import(config_module_name)
        .map_err(|e| anyhow::anyhow!("Failed to import config module {config_module_name}: {e}"))?;
    let config_class = config_module
        .getattr(config_class_name)
        .map_err(|e| anyhow::anyhow!("Failed to get config class {config_class_name}: {e}"))?;
    let py_dict = PyDict::new(py);

    for (key, value) in config {
        let py_value = config_value_to_py(py, key, value)?;
        py_dict.set_item(key, py_value)?;
    }

    let config_instance = match config_class.call((), Some(&py_dict)) {
        Ok(instance) => instance,
        Err(kwargs_err) => match config_class.call0() {
            Ok(instance) => {
                for (key, value) in config {
                    let py_value = config_value_to_py(py, key, value)?;

                    if let Err(setattr_err) = instance.setattr(key, py_value) {

View on GitHub (pinned to 18893faf8b)

Solutions

Verify the full `module:Class` config path is correct and importable
Run `python -c "from <module> import <ConfigClass>"` in the target environment
Fix any ImportError raised inside the config module (install dependencies)
Ensure PYTHONPATH/working directory includes the package

Example fix

// before
config_path = "configs:MyActorConfig"  # no module named 'configs'
// after
config_path = "my_package.config:MyActorConfig"

Defensive patterns

Strategy: validation

Validate before calling

from importlib import import_module
mod_path, _ = config_path.split(":")
import_module(mod_path)  # raises early with a clear ImportError

Try / catch

try:
    trader.add_actor(actor_config)
except Exception as e:
    if "Failed to import config module" in str(e):
        logging.error("bad config module path: %s", e)
    raise

Prevention

Keep config classes importable at module top level
Verify config paths after package refactors
Install all dependencies imported by config modules

When it happens

Trigger: Providing a `config_path` like `my_package.config:MyActorConfig` where the config module name is wrong, the module is not on sys.path, or the module raises ImportError (missing dependency) at import time.

Common situations: Typos in the config class path in node/backtest configs; config classes moved to different modules after refactoring; missing third-party imports inside the config module; wrong Python environment.

Related errors

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