Troubleshooting

Solutions for common issues encountered when running QuantAgent.

Before diving into specific issues, try the first step in the README support guide: refresh the page and re-enter your LLM API key. Many transient errors (authentication failures, stale connections) are resolved this way.

TA-Lib installation fails

TA-Lib requires a compiled C library that is not included in the Python package itself. The pip install ta-lib command often fails on fresh environments.

Solution 1 — conda-forge (recommended)

conda install -c conda-forge ta-lib

This installs both the C library and the Python bindings in one step and works reliably on macOS, Linux, and Windows.

Solution 2 — system library then pip

On Debian/Ubuntu:

sudo apt-get install libta-lib-dev
pip install ta-lib

On macOS with Homebrew:

brew install ta-lib
pip install ta-lib

For platform-specific instructions and pre-built wheels, see the official TA-Lib Python repository.

Invalid API key (401 / authentication error)

You will see an error like AuthenticationError: 401 or Incorrect API key provided when the API key is missing, malformed, or has been revoked.

Checklist

• Verify the key is entered correctly in the web interface Settings panel (no leading/trailing spaces).

• Alternatively, set it as an environment variable before starting the server:

  # OpenAI
  export OPENAI_API_KEY="sk-..."
  
  # Anthropic
  export ANTHROPIC_API_KEY="sk-ant-..."
  
  # Qwen (DashScope)
  export DASHSCOPE_API_KEY="sk-..."
  

• Confirm the key has not expired or been rotated in your provider dashboard.

• If you set the key programmatically, call update_api_key to propagate it:

  tg.update_api_key("sk-...", provider="openai")
  

Rate limit exceeded (429)

A RateLimitError: 429 means you have sent too many requests in a short window. The Pattern and Trend agents include built-in retry logic (3 attempts, 4–8 second wait), but a sustained burst of requests will exhaust retries.

Solutions

• Wait 30–60 seconds before retrying the analysis.
• Reduce the frequency of back-to-back analysis runs.
• Upgrade your API tier for higher rate limits.
• If using the Qwen provider, note that it routes through DashScope servers in Singapore; additional latency may compound rate-limit issues.

Billing or quota errors

Errors such as insufficient_quota, billing_not_active, or You exceeded your current quota indicate that your account has run out of credits or the billing method on file has failed.

Solutions

• Check your account balance and usage on the provider dashboard:
  • OpenAI: platform.openai.com/usage
  • Anthropic: console.anthropic.com
  • Qwen: dashscope.console.aliyun.com
• Add credits or update your payment method.
• Verify that your API key is assigned to the correct organization if you belong to multiple.

No data returned for a symbol

The web interface fetches market data via yfinance. Some symbols may return empty DataFrames or raise exceptions.

Common causes

• The ticker symbol is incorrect or uses an exchange-specific suffix (e.g., 9988.HK instead of BABA).
• The requested timeframe is shorter than the symbol’s available history (e.g., 1-minute data is only available for the past 7 days in yfinance).
• The symbol is delisted or not covered by Yahoo Finance.

Solutions

• Confirm the symbol is valid on finance.yahoo.com.
• For crypto, use the format BTC-USD, ETH-USD, etc.
• Try a broader date range or a longer timeframe interval.
• The system uses the most recent 45 candlesticks for analysis; ensure your date range produces at least that many candles.

Memory errors with large datasets

Passing very large kline_data dictionaries (thousands of candles) can cause memory pressure during chart generation and slow down LLM calls.

Solutions

• Reduce the dataset to the most recent 50–100 candles before passing it to TradingGraph. The chart generation tools already truncate internally (40 candles for generate_kline_image, 50 for generate_trend_image), but the full dataset is still serialized into indicator agent prompts.
• Use a larger timeframe interval to reduce the number of rows in the analysis window.

# Trim kline_data to the most recent 100 candles
import pandas as pd
df = pd.DataFrame(kline_data).tail(100)
kline_data = df.to_dict(orient="list")

Pattern or Trend agent fails with a vision error

The Pattern and Trend agents pass base64-encoded chart images to graph_llm. If graph_llm is not a vision-capable model, the request will fail with an error such as Invalid content type or image_url is not supported.

Solution

Set graph_llm_model to a model that supports image inputs:

Provider	Vision-capable models
OpenAI	gpt-4o, gpt-4o-mini
Anthropic	claude-haiku-4-5-20251001 and other Claude 3+ models
Qwen	qwen-vl-max-latest, qwen3-vl-plus

config = {
    "graph_llm_provider": "openai",
    "graph_llm_model": "gpt-4o",   # must be vision-capable
    ...
}
tg = TradingGraph(config=config)

agent_llm_model does not need to be vision-capable — it is only used for text-based tool calling. Only graph_llm_model requires vision support.

Indicator agent produces an empty report (common with Claude)

When using Claude models, the LLM may make multiple sequential tool calls before producing a final text response. If the agent exits the loop before the LLM emits its summary, indicator_report may be empty or missing.

Why this happens

Claude often returns a response with tool calls but no accompanying text content. The Indicator agent handles this with an up-to-5-iteration loop that keeps executing tool calls until the LLM produces a plain-text response. If all 5 iterations end with tool calls and no text, the agent falls back to scanning earlier messages for any non-empty text content.

Solutions

• This is expected behavior. The agent’s fallback logic should recover a valid report in most cases.
• If reports are consistently empty, try increasing agent_llm_temperature slightly (e.g., 0.2) to encourage more verbose responses.
• Switch to an OpenAI model for the agent LLM if the issue persists, as OpenAI models tend to produce text and tool calls in the same response turn.

General debugging steps

1. Check the console output

   Run the server or script from the terminal. The agents print retry warnings, tool invocation results, and error tracebacks directly to stdout.

2. Inspect `decision_prompt`

   The decision_prompt field in the final state contains the exact prompt sent to the Decision agent. If the upstream reports are empty or malformed, you will see it here.

3. Verify all dependencies are installed

   pip install -r requirements.txt
   conda install -c conda-forge ta-lib  # if TA-Lib is missing
   
4. Re-enter your API key

   Refresh the web interface and re-enter your API key in the Settings panel. Many transient failures are resolved by this step.