nautechsystems/nautilus_trader · error

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

Error message

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

What it means

This error is raised by `create_config_instance` in the backtest node when importing the Python module that holds a component's configuration class fails. The library builds backtest nodes by dynamically importing a Python module and reading the config class from it; if `py.import(module_name)` returns an Err (module missing, broken, or raising on import), the underlying Python exception is wrapped with this message via anyhow. It is a module-resolution/import failure, not a config-value problem.

Source

Thrown at crates/backtest/src/python/node.rs:518

) -> anyhow::Result<Option<Bound<'py, PyAny>>> {
    if config_path.is_empty() && config.is_empty() {
        log::debug!("No config_path or empty config, using None");
        return Ok(None);
    }

    let config_parts: Vec<&str> = config_path.split(':').collect();
    if config_parts.len() != 2 {
        anyhow::bail!("config_path must be in format 'module.path:ClassName', was {config_path}");
    }
    let (config_module_name, config_class_name) = (config_parts[0], config_parts[1]);

    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}"))?;

    // Convert config dict to Python dict
    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)?;
    }

    log::debug!("Created config dict: {py_dict:?}");

    // Try kwargs first, then default constructor with setattr
    let config_instance = match config_class.call((), Some(&py_dict)) {
        Ok(instance) => {
            log::debug!("Created config instance with kwargs");

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Check the module path string for typos and confirm it matches the real dotted module path (e.g. `my_pkg.config`, not a file path)
  2. Add the module's parent directory to PYTHONPATH or `sys.path` before creating the node, or install the package with `pip install -e .`
  3. Run `python -c "import <module>"` in the same environment to see the real underlying import error (it is appended to this message)
  4. If a dependency of the module is missing or the module raises at import time, fix that dependency/error; the wrapped `{e}` shows the cause

Example fix

// before
create_importable_component(py, config, module="strategies.configs", ...)  // module not on sys.path
// after
import sys; sys.path.insert(0, "/path/to/project")  # or set PYTHONPATH
create_importable_component(py, config, module="strategies.configs", ...)
Defensive patterns

Strategy: try-catch

Validate before calling

# Python-side pre-check before creating the node
import importlib
def module_importable(name):
    try:
        importlib.import_module(name)
        return True
    except Exception:
        return False

Try / catch

match create_importable_component(...) {
    Err(e) if e.to_string().contains("Failed to import config module") => {
        eprintln!("config module missing/unimportable: {e:#}"); // fix sys.path or module
    }
    Err(e) => return Err(e),
    Ok(v) => v,
}

Prevention

When it happens

Trigger: Calling `create_importable_component`/`create_config_instance` with a `config_module_name` that is not importable: a typo'd dotted path, a module not on `sys.path`, a module that raises ImportError/SyntaxError/other exception at import time, or an installed package version that renamed or removed the module.

Common situations: Running a backtest from a script whose custom strategy/config module directory is not on PYTHONPATH; a package refactor renamed the config module (e.g. after a nautilus version upgrade); a custom module has an import-time error (bad import inside it, syntax error); missing optional dependency imported by the config module.

Related errors

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