# How to Debug Issues with Qwen-Agent: A Complete Troubleshooting Guide

> Troubleshoot Qwen-Agent effectively by enabling DEBUG logging and tracing failures across agent runtime, LLM wrapper, and utility layers. Quickly find and fix Qwen-Agent issues.

- Repository: [Qwen/Qwen-Agent](https://github.com/qwenlm/Qwen-Agent)
- Tags: troubleshooting-guide
- Published: 2026-03-09

---

**Enable DEBUG logging via `logger.setLevel('DEBUG')` and trace failures through the agent runtime, LLM wrapper, and utility layers to rapidly identify root causes in Qwen-Agent.**

Qwen-Agent is a modular agent framework built on large language models that routes messages between users, tools, and LLMs. When you need to debug issues with Qwen-Agent, you will typically trace problems through three architectural layers: the **core runtime** that handles message routing, the **LLM interface** that manages retries and caching, and the **utility layer** that provides logging and error formatting.

## Understanding Qwen-Agent's Debug Architecture

Debugging Qwen-Agent requires familiarity with its three-layer architecture. Each layer exposes specific entry points where errors surface and where you can inject logging.

### Core Runtime Layer

The core runtime lives in [`qwen_agent/agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agent.py) and manages the agent's execution loop, tool registration, and message dispatch. Key sections include:

- **Lines 31-73**: The `run` loop and tool call handling
- **Lines 88-103**: Tool initialization and the `_call_tool` method where "Tool X does not exist" errors originate

When an agent fails to invoke a tool or enters an infinite loop, the traceback will point to these sections.

### LLM Interface Layer

The LLM abstraction resides in [`qwen_agent/llm/base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/base.py) and wraps various model backends (OpenAI, DashScope, Transformers). This layer implements:

- **Lines 56-89**: Retry logic, caching, and token-budget truncation
- **Lines 108-124**: Exponential back-off logic in `retry_model_service` and `retry_model_service_iterator`
- **Lines 642-665**: The `_truncate_input_messages_roughly` function that trims conversations exceeding context windows

Errors such as `ModelServiceError`, timeouts, or "maximum context length" exceptions originate here.

### Utility and Tooling Layer

Helper functions and logging utilities live in [`qwen_agent/utils/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/utils/utils.py) and [`qwen_agent/log.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/log.py):

- **`print_traceback`** (lines 86-92 in [`utils/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/utils/utils.py)): Formats the last three frames of exceptions and logs them at the appropriate level
- **Centralized logger** ([`log.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/log.py) lines 15-33): A single logger instance used across all components

Individual tools (e.g., `code_interpreter`, `web_search`) also log their own progress in `qwen_agent/tools/`.

## Enabling Debug Logging in Qwen-Agent

All components use the **single logger instance** defined in [`qwen_agent/log.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/log.py). To obtain verbose output including timestamps, file names, and line numbers, adjust the logging level before running your agent:

```python
from qwen_agent.log import logger

# Enable most verbose logging

logger.setLevel('DEBUG')

# Or use INFO for default verbosity

logger.setLevel('INFO')

```

When `DEBUG` is enabled, the logger prints every tool invocation, LLM request, cache lookup, and retry attempt. This is the first step in any debugging session.

## Step-by-Step Debugging Workflow

Follow this systematic approach to diagnose failures in Qwen-Agent applications.

### 1. Enable Detailed Logging

Start every debugging session by setting the logger to `DEBUG` level. This reveals the exact line numbers where failures occur and shows the full content of messages passed between components.

### 2. Identify the Failing Component

Check the log output to determine whether the error originates in the **agent runtime** or the **LLM interface**:

- **Agent-level errors**: Look for messages like "Tool XYZ does not exist" originating from `Agent._call_tool` in [`agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/agent.py) (lines 88-103).
- **LLM-level errors**: Look for `ModelServiceError` or timeout messages from `BaseChatModel.chat` in [`base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/base.py) (lines 56-89).

### 3. Inspect the Exception Trace

When tools fail or LLM calls error out, Qwen-Agent uses the `print_traceback` utility (lines 86-92 in [`utils/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/utils/utils.py)) to format the last three frames. If you see a generic message like "An error occurred when calling tool …", scroll up in the logs to find the formatted traceback that reveals the underlying exception.

### 4. Check Cache and Retry Behavior

- **Cache**: The `BaseChatModel` constructor creates a disk cache (`diskcache.Cache`) when `cache_dir` is supplied. If the cache library is missing, it is silently disabled with a warning (lines 98-105 in [`base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/base.py)). Verify that `diskcache` is installed (`pip install diskcache`) or disable caching to rule out stale data.
- **Retry**: Exponential back-off logic lives in `retry_model_service` (lines 108-124 in [`base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/base.py)). If you suspect transient network errors, increase `max_retries` in your model configuration.

### 5. Validate Input Token Size

If conversations are truncated or you receive "maximum context length" errors, examine the `_truncate_input_messages_roughly` function (lines 642-665 in [`base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/base.py)). You can increase `DEFAULT_MAX_INPUT_TOKENS` in [`qwen_agent/settings.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/settings.py) or shorten the user prompt to fit within the model's context window.

### 6. Inspect Tool-Specific Diagnostics

Each tool logs its own progress. For example, the code interpreter logs Docker image handling at lines 184-210 in [`code_interpreter.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/code_interpreter.py). If a specific tool fails, consult its source file in `qwen_agent/tools/` for additional `logger.debug`, `logger.info`, or `logger.warning` statements.

## Common Debugging Scenarios and Solutions

### Tool Registration Failures

If you encounter "Tool X does not exist" errors in the logs, the failure originates in `Agent._init_tool` or `Agent._call_tool` (lines 88-103 in [`agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/agent.py)). This indicates the tool name is not registered in the `TOOL_REGISTRY` defined in [`qwen_agent/tools/__init__.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/__init__.py). Verify that the tool name in your `function_list` parameter matches the registered name exactly.

### ModelServiceError and Retry Logic

`ModelServiceError` exceptions bubble up through `BaseChatModel._chat` and the `retry_model_service` wrapper (lines 78-90 and 108-124 in [`base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/base.py)). The error code determines the behavior: `400` indicates a bad request (e.g., malformed JSON or invalid parameters) that will not retry, while other codes trigger exponential back-off. Check the error code in the logs to determine if you need to fix the request payload or simply increase `max_retries` for transient network issues.

### Context Length Truncation Issues

When conversations exceed the model's token limit, the `_truncate_input_messages_roughly` function (lines 642-665 in [`base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/base.py)) trims the message history. If you see "maximum context length" errors or notice that earlier messages disappear from the conversation, examine the debug logs for entries showing `ALL tokens: X, Available tokens: Y`. You can increase the token budget by modifying `DEFAULT_MAX_INPUT_TOKENS` in [`qwen_agent/settings.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/settings.py) or by shortening the input prompt.

### Cache and Memory Problems

The LLM wrapper uses `diskcache.Cache` when a `cache_dir` is provided (lines 98-105 in [`base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/base.py)). If the `diskcache` library is not installed, caching is silently disabled with a warning. To rule out stale cache entries causing unexpected responses, either install `diskcache` (`pip install diskcache`) or remove the `cache_dir` parameter from your model configuration. For memory-related issues, the `Memory` class in [`memory.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/memory.py) (line 130) logs queries and results that you can inspect when vector store retrieval fails.

## Summary

- **Enable DEBUG logging** immediately using `logger.setLevel('DEBUG')` from [`qwen_agent/log.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/log.py) to expose timestamps, file names, and line numbers for every operation.
- **Trace failures through three layers**: the core runtime ([`agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/agent.py)), the LLM interface ([`llm/base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/llm/base.py)), and utility helpers ([`utils/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/utils/utils.py)).
- **Inspect tool errors** in `Agent._call_tool` (lines 88-103) and verify tool names against the `TOOL_REGISTRY`.
- **Diagnose LLM failures** by examining `ModelServiceError` codes in `BaseChatModel` (lines 78-90) and adjusting `max_retries` or fixing malformed requests.
- **Resolve context truncation** by monitoring `_truncate_input_messages_roughly` (lines 642-665) and adjusting `DEFAULT_MAX_INPUT_TOKENS` in [`settings.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/settings.py).

## Frequently Asked Questions

### How do I enable verbose logging in Qwen-Agent?

Import the centralized logger from [`qwen_agent/log.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/log.py) and set its level to `DEBUG`. This activates detailed output across all components, including timestamps, source file names, and line numbers for every tool invocation, LLM request, and retry attempt.

### What does the "Tool X does not exist" error mean?

This error originates in `Agent._init_tool` or `Agent._call_tool` within [`qwen_agent/agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agent.py) (lines 88-103). It indicates that the tool name specified in your `function_list` does not match any entry in the `TOOL_REGISTRY` defined in [`qwen_agent/tools/__init__.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/__init__.py). Verify the tool name spelling and registration.

### How can I fix ModelServiceError timeouts?

`ModelServiceError` exceptions bubble up through `BaseChatModel._chat` in [`qwen_agent/llm/base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/base.py). Check the error code in the logs: a `400` code indicates a malformed request that will not retry, while other codes trigger exponential back-off. For transient network issues, increase the `max_retries` parameter in your model configuration.

### Why is my conversation being truncated?

When input exceeds the model's context window, the `_truncate_input_messages_roughly` function in [`qwen_agent/llm/base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/base.py) (lines 642-665) trims the message history. You will see log entries showing token counts versus available tokens. To prevent truncation, increase `DEFAULT_MAX_INPUT_TOKENS` in [`qwen_agent/settings.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/settings.py) or shorten your input prompts.