# TradingAgents Debug Mode and Trace Logging: A Complete Troubleshooting Guide

> Master TradingAgents troubleshooting with debug mode and trace logging. Capture execution traces, pretty-print messages, and save detailed JSON logs for seamless multi-agent workflow issue resolution.

- Repository: [Tauric Research/TradingAgents](https://github.com/TauricResearch/TradingAgents)
- Tags: how-to-guide
- Published: 2026-03-23

---

**Enable debug mode in TradingAgents by setting `debug=True` when instantiating `TradingAgentsGraph` to capture full LangGraph execution traces, pretty-print intermediate messages, and persist detailed JSON logs for troubleshooting multi-agent trading workflows.**

The TradingAgents framework provides robust debugging capabilities that allow developers to inspect every step of complex multi-agent trading decisions. By activating debug mode and trace logging, you can monitor the complete LangGraph pipeline execution, from initial market analysis through final trade decisions, using implementations found in [`tradingagents/graph/trading_graph.py`](https://github.com/TauricResearch/TradingAgents/blob/main/tradingagents/graph/trading_graph.py) and [`cli/main.py`](https://github.com/TauricResearch/TradingAgents/blob/main/cli/main.py).

## How Debug Mode Works in TradingAgents

When `debug=True` is passed to the `TradingAgentsGraph` constructor, the framework switches from standard invocation to streaming mode with comprehensive trace collection. Instead of calling `self.graph.invoke()` directly, the `propagate` method iterates over `self.graph.stream()` and captures every chunk emitted during the graph execution.

The core logic resides in [`tradingagents/graph/trading_graph.py`](https://github.com/TauricResearch/TradingAgents/blob/main/tradingagents/graph/trading_graph.py). When debug mode is active, the method initializes an empty `trace` list and populates it with every chunk from the stream. Each chunk's final message is immediately pretty-printed to the console, providing real-time visibility into agent communications and tool calls.

### The Debug Execution Path in trading_graph.py

The following implementation shows the conditional logic that switches between standard and debug execution modes:

```python
if self.debug:
    # Debug mode with tracing

    trace = []
    for chunk in self.graph.stream(init_agent_state, **args):
        if len(chunk["messages"]) == 0:
            pass
        else:
            chunk["messages"][-1].pretty_print()
            trace.append(chunk)

    final_state = trace[-1]
else:
    # Standard mode without tracing

    final_state = self.graph.invoke(init_agent_state, **args)

```

*When debug mode is enabled, every graph step is streamed, printed, and stored in memory, while standard mode runs silently with only the final state returned.*

## Enabling Debug Mode and Trace Logging

You can activate debug mode through three primary interfaces: programmatic instantiation, the interactive CLI, or standalone scripts. Each method provides the same underlying trace collection while adapting to different workflow requirements.

### Programmatic Debugging

For ad-hoc analysis or automated testing, instantiate `TradingAgentsGraph` with `debug=True` and a custom configuration:

```python
from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

# Optional: customize LLM providers or debate rounds

config = DEFAULT_CONFIG.copy()
config["max_debate_rounds"] = 2

# Enable debug mode

graph = TradingAgentsGraph(debug=True, config=config)

# Execute with live trace output

final_state, decision = graph.propagate("AAPL", "2024-04-30")
print("Decision:", decision)

```

*Key points:*

- `debug=True` activates streaming mode and live pretty-printing
- The returned `final_state` contains structured outputs including agent reports and debate states
- The complete trace remains accessible within the graph instance for post-run inspection

### CLI-Driven Debug Run

The interactive command-line interface automatically enables debug mode when constructing the graph. Located in [`cli/main.py`](https://github.com/TauricResearch/TradingAgents/blob/main/cli/main.py), this interface builds the graph with `debug=True` and manages trace collection automatically.

```bash

# Launch the interactive CLI with built-in debug tracing

python -m tradingagents.cli.main

```

During execution, the CLI:

- Displays a live Rich layout showing real-time agent statuses
- Accumulates streamed chunks in a local `trace` variable
- Extracts `final_state = trace[-1]` upon completion
- Writes comprehensive JSON logs to `eval_results/<ticker>/TradingAgentsStrategy_logs/`

### One-Off Script Execution

The repository includes a minimal example in [`main.py`](https://github.com/TauricResearch/TradingAgents/blob/main/main.py) demonstrating standalone debug usage:

```python
from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

config = DEFAULT_CONFIG.copy()
config["deep_think_llm"] = "gpt-5-mini"
config["quick_think_llm"] = "gpt-5-mini"

ta = TradingAgentsGraph(debug=True, config=config)

# Stream with trace logging enabled

_, decision = ta.propagate("NVDA", "2024-05-10")
print(decision)

```

Running this script prints step-by-step execution traces to the console and stores the final state in the evaluation results directory.

## Trace Persistence and Log Locations

Debug mode generates persistent logs in specific directory structures for post-run analysis. The `TradingAgentsGraph._log_state` method handles JSON serialization of the complete execution history.

### JSON State Logs

In debug mode, the framework writes accumulated states to:

```python
with open(
    f"eval_results/{self.ticker}/TradingAgentsStrategy_logs/full_states_log_{trade_date}.json",
    "w",
    encoding="utf-8",
) as f:
    json.dump(self.log_states_dict, f, indent=4)

```

This file contains the full `log_states_dict` including the final state with all agent deliberations, tool outputs, and intermediate reasoning steps.

### CLI Message Logs

When using the interactive CLI, additional logging occurs through decorators defined around line 64 in [`cli/main.py`](https://github.com/TauricResearch/TradingAgents/blob/main/cli/main.py). This generates a `message_tool.log` file recording every message and tool call emitted during the streamed execution, complementing the structured JSON output with human-readable text logs.

## Summary

- **Debug activation**: Set `debug=True` in `TradingAgentsGraph` constructor to enable streaming execution and trace collection
- **Real-time visibility**: The `propagate` method in [`tradingagents/graph/trading_graph.py`](https://github.com/TauricResearch/TradingAgents/blob/main/tradingagents/graph/trading_graph.py) calls `pretty_print()` on every chunk's final message when debug mode is active
- **Trace storage**: All streamed chunks are appended to an in-memory `trace` list, with `final_state = trace[-1]` providing the complete decision context
- **Log locations**: JSON state logs write to `eval_results/{ticker}/TradingAgentsStrategy_logs/`, while the CLI generates additional `message_tool.log` files
- **Multiple interfaces**: Debug mode works identically across programmatic API, interactive CLI ([`cli/main.py`](https://github.com/TauricResearch/TradingAgents/blob/main/cli/main.py)), and standalone scripts ([`main.py`](https://github.com/TauricResearch/TradingAgents/blob/main/main.py))

## Frequently Asked Questions

### How do I enable debug mode in TradingAgents without using the CLI?

Instantiate the `TradingAgentsGraph` class with the `debug=True` parameter in your Python script. Import the class from `tradingagents.graph.trading_graph`, create your configuration dictionary, and pass both to the constructor before calling `propagate()`.

### What is the difference between debug mode and standard mode?

In standard mode, `TradingAgentsGraph.propagate()` calls `self.graph.invoke()` and returns only the final state. In debug mode, it streams execution via `self.graph.stream()`, captures every chunk in a `trace` list, pretty-prints intermediate messages, and extracts the final state from the last trace element.

### Where are the debug logs stored after running TradingAgents?

Debug logs are persisted in two locations: structured JSON files containing full state histories are written to `eval_results/{ticker}/TradingAgentsStrategy_logs/full_states_log_{trade_date}.json`, and when using the CLI, text-based message logs are saved as `message_tool.log` in the same directory.

### Can I customize which components are traced in debug mode?

While the built-in debug mode captures all LangGraph stream chunks, you can modify the logging behavior by adjusting the configuration dictionary passed to `TradingAgentsGraph`. The [`default_config.py`](https://github.com/TauricResearch/TradingAgents/blob/main/default_config.py) file provides the base configuration that can be overridden to adjust LLM callbacks and verbosity levels, though the core trace collection logic remains consistent across all debug-enabled runs.