nautechsystems/nautilus_trader · error · ValueError

run_config_id is required when a BacktestNode is provided

Error message

run_config_id is required when a BacktestNode is provided

What it means

create_tearsheet can render the 'bars_with_fills' chart directly from a BacktestNode's live engine state, which is keyed by run_config_id. When a node is supplied but no run_config_id can be resolved (neither the argument nor result.run_config_id), the library cannot look up which backtest run to inspect and raises ValueError instead of guessing.

Solutions

  1. Pass the run_config_id argument explicitly to create_tearsheet (the id of the BacktestRunConfig added to node.configs).
  2. Capture the run_config_id from the node before running (node.configs[0].id) and store it on/with the BacktestResult.
  3. If no per-run engine state is needed, omit node= or drop 'bars_with_fills' from config.chart_names so the node is not required.

Example fix

// before
tearsheet = create_tearsheet(result, config=config, node=node)
// after
tearsheet = create_tearsheet(result, config=config, node=node, run_config_id=node.configs[0].id)
Defensive patterns

Strategy: validation

Validate before calling

if node is not None and not (run_config_id or getattr(result, 'run_config_id', None)):
    raise ValueError('Provide run_config_id when passing a BacktestNode to create_tearsheet')

Try / catch

try:
    path = create_tearsheet(result, config=config, node=node, run_config_id=run_config_id)
except ValueError as e:
    if 'run_config_id is required' in str(e):
        run_config_id = node.configs[0].id
        path = create_tearsheet(result, config=config, node=node, run_config_id=run_config_id)
    else:
        raise

Prevention

When it happens

Trigger: Calling create_tearsheet(..., node=BacktestNode(...)) without passing run_config_id, where the BacktestResult also lacks a run_config_id (e.g. a result produced by an older code path or manually constructed).

Common situations: Passing a node only when the config asks for bars_with_fills while forgetting run_config_id; reusing results serialized before run_config_id was added; copying example code that only sets node=.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at python/nautilus_trader/analysis/tearsheet.py:516


def _create_tearsheet_from_result(
    result: BacktestResult,
    node: BacktestNode | None,
    run_config_id: str | None,
    currency: Currency | None,
    output_path: str | None,
    title: str,
    config: TearsheetConfig | None,
    benchmark_returns: pd.Series | None,
    benchmark_name: str,
) -> str | None:
    resolved_run_config_id = run_config_id or result.run_config_id
    needs_engine = config is not None and "bars_with_fills" in config.chart_names
    if needs_engine and node is None:
        raise ValueError("A BacktestNode is required for the bars_with_fills chart")
    if node is not None and resolved_run_config_id is None:
        raise ValueError("run_config_id is required when a BacktestNode is provided")
    if node is not None and resolved_run_config_id is not None:
        _validate_result_node_state(node, resolved_run_config_id)

    engine_view = (
        _BacktestNodeEngineView(node, resolved_run_config_id)
        if node is not None and resolved_run_config_id is not None
        else None
    )
    returns = _result_returns_series(result)
    run_info = _result_run_info(result)
    account_info = _result_account_info(result, node, resolved_run_config_id, currency)

    if title == "NautilusTrader Backtest Results":
        run_started = _format_optional_iso8601(result.run_started)
        title = f"<b>NautilusTrader</b> v{NAUTILUS_VERSION} - Backtest Results"
        title += f"<br><sub>Run started: {run_started}</sub>"

    return create_tearsheet_from_stats(

View on GitHub (pinned to 18893faf8b)