Troubleshooting

This guide provides solutions to common issues and debugging tips, including topics on:

• Authentication or login errors
• Frequently asked questions (FAQs)
• Debugging tips
• Existing GitHub Issues similar to yours or creating new Issues

Authentication or login errors

• Error: Qwen OAuth free tier was discontinued on 2026-04-15

  • Cause: Qwen OAuth is no longer available as of April 15, 2026.
  • Solution: Switch to a different authentication method. Run qwen → /auth and choose one of:
    • API Key: Use an API key from Alibaba Cloud Model Studio (Beijing  / intl ). See the API setup guide (Beijing  / intl ).
    • Alibaba Cloud Coding Plan: Subscribe for a fixed monthly fee with higher quotas. See the Coding Plan guide (Beijing  / intl ).

• Error: UNABLE_TO_GET_ISSUER_CERT_LOCALLY, UNABLE_TO_VERIFY_LEAF_SIGNATURE, or unable to get local issuer certificate

  • Cause: You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js.
  • Solution: Set the NODE_EXTRA_CA_CERTS environment variable to the absolute path of your corporate root CA certificate file.
    • Example: export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

• Error: Connection error. (cause: fetch failed) against a self-signed endpoint

  • Cause: You are pointing Qwen Code at a self-hosted server (for example a local model behind https://) whose TLS certificate is self-signed, so Node.js rejects it.
  • Solution: Prefer trusting the certificate via NODE_EXTRA_CA_CERTS (above). If that is not practical in a trusted lab/private network, skip verification with the --insecure flag (or QWEN_TLS_INSECURE=1):
    • Example: qwen --insecure --openaiBaseUrl https://192.168.1.10:8080 ...
    • Warning: Disabling verification removes protection against man-in-the-middle attacks. Only use it for endpoints you fully trust.

• Error: Device authorization flow failed: fetch failed

  • Cause: Node.js could not reach Qwen OAuth endpoints (often a proxy or SSL/TLS trust issue). When available, Qwen Code will also print the underlying error cause (for example: UNABLE_TO_VERIFY_LEAF_SIGNATURE). Note: this error is specific to the legacy Qwen OAuth flow.
  • Solution:
    • If you are still using Qwen OAuth, switch to API Key or Coding Plan via /auth.
    • If you are behind a proxy, set it via qwen --proxy <url> (or the proxy setting in settings.json).
    • If your network uses a corporate TLS inspection CA, set NODE_EXTRA_CA_CERTS as described above.

• Issue: Unable to display UI after authentication failure

  • Cause: If authentication fails after selecting an authentication type, the security.auth.selectedType setting may be persisted in settings.json. On restart, the CLI may get stuck trying to authenticate with the failed auth type and fail to display the UI.
  • Solution: Clear the security.auth.selectedType configuration item in your settings.json file:
    • Open ~/.qwen/settings.json (or ./.qwen/settings.json for project-specific settings)
    • Remove the security.auth.selectedType field
    • Restart the CLI to allow it to prompt for authentication again

Frequently asked questions (FAQs)

• Q: How do I update Qwen Code to the latest version?

  • A: If you installed Qwen Code with the standalone installer, rerun the standalone install command. If you installed it globally via npm, update it using the command npm install -g @qwen-code/qwen-code@latest. If you compiled it from source, pull the latest changes from the repository, and then rebuild using the command npm run build.

• Q: Where are the Qwen Code configuration or settings files stored?

  • A: The Qwen Code configuration is stored in two settings.json files:

    1. In your home directory: ~/.qwen/settings.json.
    2. In your project’s root directory: ./.qwen/settings.json.

    Refer to Qwen Code Configuration for more details.

• Q: Why don’t I see cached token counts in my stats output?

  • A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (e.g., Alibaba Cloud Model Studio API key or Google Cloud Vertex AI). You can still view your total token usage using the /stats command.

• Q: A customization (extension, hook, skill, MCP server, or subagent) seems to be breaking Qwen Code. How do I isolate it?

  • A: Start Qwen Code with the --safe-mode flag to disable all customizations — context files, hooks, extensions, skills, MCP servers, custom subagents (only built-in subagents load), permission rules, settings-sourced approval mode overrides, memory features, cross-session messaging, and sandbox settings — for the session. Note: the CLI flags --yolo and --approval-mode still take effect in safe mode. If the problem disappears in safe mode, re-enable your customizations one at a time to find the culprit.
    • Example: qwen --safe-mode
    • Alternative: set the environment variable QWEN_CODE_SAFE_MODE=true if the CLI cannot accept flags.
    • Note: unlike the flag, an exported QWEN_CODE_SAFE_MODE is inherited by child processes. A qwen serve daemon or an editor started from that shell hosts every one of its sessions in safe mode, so those sessions are suppressed too: they write no session record, and other sessions can neither list nor message them. Unset the variable for the daemon rather than leaving it exported in the shell that starts it.
    • Note: “MCP servers” here means servers configured in settings.json / project .mcp.json — local, ambient state that safe mode is meant to isolate against. MCP servers you explicitly supply for the current invocation (an embedding ACP client’s session/new mcpServers, or --mcp-config) are not local/ambient state and are still honored under safe mode.

Attachment upload returns HTTP 413 behind a reverse proxy

A proxy may reject a request before it reaches qwen serve, even when the attachment is within the daemon’s 8 MiB file limit. Raising only a daemon body limit does not change the proxy limit.

Use a daemon and TypeScript SDK/Web Shell build that supports session_attachment_chunk_upload. Attachments larger than 512 KiB are then uploaded in 512 KiB requests without changing their bytes or image quality. Older daemons keep the single-request upload path. If you operate the proxy, you can also raise its request-body limit to accommodate the original attachment request. Proxies with limits below 512 KiB still need a configuration change.

The attachment limit remains 8 MiB. If an upload expires or the daemon restarts, retry the attachment from the UI. A completed upload whose response was lost can remain in the session’s attachments; cancellation does not remove a file that has already completed.

Common error messages and solutions

• Error: EADDRINUSE (Address already in use) when starting an MCP server.

  • Cause: Another process is already using the port that the MCP server is trying to bind to.
  • Solution: Either stop the other process that is using the port or configure the MCP server to use a different port.

• Error: Command not found (when attempting to run Qwen Code with qwen).

  • Cause: The CLI is not correctly installed or it is not in your system’s PATH.
  • Solution: The update depends on how you installed Qwen Code:
    • If you installed qwen with the standalone installer, rerun the standalone install command and then open a new terminal.
    • If you installed qwen globally, check that your npm global binary directory is in your PATH. You can update using the command npm install -g @qwen-code/qwen-code@latest.
    • If you are running qwen from source, ensure you are using the correct command to invoke it (e.g. node packages/cli/dist/index.js ...). To update, pull the latest changes from the repository, and then rebuild using the command npm run build.

• Error: MODULE_NOT_FOUND or import errors.

  • Cause: Dependencies are not installed correctly, or the project hasn’t been built.
  • Solution:
    1. Run npm install to ensure all dependencies are present.
    2. Run npm run build to compile the project.
    3. Verify that the build completed successfully with npm run start.

• Error: “Operation not permitted”, “Permission denied”, or similar.

  • Cause: When sandboxing is enabled, Qwen Code may attempt operations that are restricted by your sandbox configuration, such as writing outside the project directory or system temp directory.
  • Solution: Refer to the Configuration: Sandboxing documentation for more information, including how to customize your sandbox configuration.

• Qwen Code is not running in interactive mode in “CI” environments

  • Issue: Qwen Code does not enter interactive mode (no prompt appears) if an environment variable starting with CI_ (e.g. CI_TOKEN) is set. This is because the is-in-ci package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment.
  • Cause: The is-in-ci package checks for the presence of CI, CONTINUOUS_INTEGRATION, or any environment variable with a CI_ prefix. When any of these are found, it signals that the environment is non-interactive, which prevents the CLI from starting in its interactive mode.
  • Solution: If the CI_ prefixed variable is not needed for the CLI to function, you can temporarily unset it for the command. e.g. env -u CI_TOKEN qwen

• DEBUG mode not working from project .env file

  • Issue: Setting DEBUG=true in a project’s .env file doesn’t enable debug mode for the CLI.
  • Cause: The DEBUG and DEBUG_MODE variables are automatically excluded from project .env files to prevent interference with the CLI behavior.
  • Solution: Use a .qwen/.env file instead, or configure the advanced.excludedEnvVars setting in your settings.json to exclude fewer variables.

• Trackpad scrolling in tmux changes prompt history instead of scrolling the conversation

  • Issue: In a tmux session, trackpad or wheel scrolling may cycle through previous prompts, similar to pressing Up Arrow or Down Arrow.
  • Cause: tmux can translate wheel gestures into plain arrow-key sequences. Those sequences are indistinguishable from real arrow-key presses by the time qwen-code receives them.
  • Solution: If screen reader mode is disabled, make sure ui.useTerminalBuffer is enabled; then use Shift+Up / Shift+Down, or the mouse wheel when tmux forwards wheel events to the app (requires ui.mouseTracking). To hand plain Up Arrow / Down Arrow to the viewport while the composer is empty, set ui.arrowKeysScrollTranscript to true; input history is then reachable with Ctrl+P / Ctrl+N. If you prefer host scrollback, adjust your tmux mouse bindings for wheel events.

• Right-click does nothing, links do not open, or text cannot be selected in the terminal

  • Issue: Native right-click context menus, OSC 8 hyperlink clicks, and terminal-native text selection stop working while Qwen Code is running.
  • Cause: When ui.mouseTracking is enabled (the default), Qwen Code captures all mouse events via SGR mouse tracking to power in-app text selection, click-to-position, row hover, history-item toggling, and viewport scrolling. The terminal forwards every mouse event to the app instead of handling it natively. Qwen Code supplies its own replacements while tracking is on: a single click opens an http(s) OSC 8 hyperlink, and right-click on a link or text selection opens an in-app context menu.
  • Solution: If you prefer the terminal’s native handling, set "ui.mouseTracking": false in your settings.json. This turns off all in-app mouse interaction, including the in-app link open and context menu. In Virtualized History (ui.useTerminalBuffer: true, the default), the wheel will no longer scroll the transcript — use Shift+↑/↓, PgUp/PgDn, or Ctrl+Home/End instead. To also restore native terminal scrollback, set "ui.useTerminalBuffer": false. Requires restart.

IDE Companion not connecting

• Ensure VS Code has a single workspace folder open.
• Restart the integrated terminal after installing the extension so it inherits:
  • QWEN_CODE_IDE_WORKSPACE_PATH
  • QWEN_CODE_IDE_SERVER_PORT
• If running in a container, verify host.docker.internal resolves. Otherwise, map the host appropriately.
• Reinstall the companion with /ide install and use “Qwen Code: Run” in the Command Palette to verify it launches.

Connection resets on some networks (TLS-stack-selective middleboxes)

• Issue: On some carrier or enterprise networks, HTTPS connections to API endpoints are reset (TCP RST) immediately after the TLS ClientHello. Qwen Code keeps retrying (ECONNRESET is a retryable transport error) until the budget is exhausted, then surfaces a generic connection error — while curl, Python, and other tools work fine on the same machine and network at the same moment.
• Cause: Some middleboxes filter connections by TLS ClientHello fingerprint and reset those emitted by particular TLS stack generations. On affected links, OpenSSL 3.0-era stacks and Electron/BoringSSL (used by the VS Code extension and the daemon) are reset, while OpenSSL 3.5-generation stacks — including current Node.js builds — connect normally.
• Solution: Make the connection with a 3.5-generation TLS stack:
  • CLI: use an up-to-date build of a supported Node.js line (current Node 22/24/25 builds all ship a 3.5-generation OpenSSL). Older builds of the same major may still be on an affected generation — update rather than pin to an old minor.
  • VS Code extension / daemon: the extension runs on Electron’s TLS stack and cannot change it client-side. Run a small local relay — a local process on a 3.5-generation stack — and point Qwen Code at it via the model base URL override (the custom endpoint in settings.json, or --openaiBaseUrl for the CLI), so the TLS egress happens with the newer stack.
• How to distinguish this from a flaky network:
  • the reset is deterministic — every attempt fails immediately, across retries, and does not recover over time;
  • on the same machine and moment, other TLS stacks succeed against the same endpoint;
  • pinning TLS versions or changing DNS resolution does not help.

Exit Codes

The Qwen Code uses specific exit codes to indicate the reason for termination. This is especially useful for scripting and automation.

Debugging Tips

• CLI debugging:

  • Use the --verbose flag (if available) with CLI commands for more detailed output.
  • Check the CLI logs, often found in a user-specific configuration or cache directory.

• Core debugging:

  • Check the server console output for error messages or stack traces.
  • Increase log verbosity if configurable.
  • Use Node.js debugging tools (e.g. node --inspect) if you need to step through server-side code.

• Tool issues:

  • If a specific tool is failing, try to isolate the issue by running the simplest possible version of the command or operation the tool performs.
  • For run_shell_command, check that the command works directly in your shell first.
  • For file system tools, verify that paths are correct and check the permissions.

• Pre-flight checks:

  • Always run npm run preflight before committing code. This can catch many common issues related to formatting, linting, and type errors.

Existing GitHub Issues similar to yours or creating new Issues

If you encounter an issue that was not covered here in this Troubleshooting guide, consider searching the Qwen Code Issue tracker on GitHub . If you can’t find an issue similar to yours, consider creating a new GitHub Issue with a detailed description. Pull requests are also welcome!