mirror of
https://github.com/QwenLM/qwen-code.git
synced 2026-04-28 19:52:02 +00:00
89167618d8
* docs: update authentication methods to reflect OAuth discontinuation Remove deprecated Qwen OAuth references and update documentation to direct users to valid authentication methods (API Key, Coding Plan, or Local Inference) following the OAuth free tier discontinuation on 2026-04-15. Closes #3316 * docs: fix quickstart auth description to match actual /auth UI The /auth command shows three options: Alibaba Cloud Coding Plan, API Key, and Qwen OAuth (discontinued). Updated quickstart.md to accurately reflect this UI instead of splitting into Option A/B/C. Also updated settings.md, commands.md, and troubleshooting.md with minor OAuth-related cleanups. * docs: update .qwen workspace description in quickstart Remove reference to 'Qwen account' since OAuth is discontinued. The .qwen directory is created by Qwen Code itself for storing credentials, configuration, and session data. * docs: fix warning block formatting in quickstart - Add missing '>' continuation for the OAuth discontinuation warning block Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: update README Qwen3.6-Plus description - Remove mention of running Qwen3.6-Plus locally via Ollama/vLLM - Keep only the Alibaba Cloud ModelStudio API key option Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: address review feedback - remove Local Inference from auth, add dual-region links - Local Inference removed from auth method lists, kept as separate 'Local Model Setup' section with detailed Ollama/vLLM config examples - All links now provide dual-region URLs (Beijing + intl) - .qwen workspace note restored to original meaning (cost tracking) - Device auth flow error kept scoped to legacy OAuth - API setup guide links updated with confirmed intl URL --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
129 lines
10 KiB
Markdown
129 lines
10 KiB
Markdown
# 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](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)). See the API setup guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [intl](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)).
|
|
- **Alibaba Cloud Coding Plan**: Subscribe for a fixed monthly fee with higher quotas. See the Coding Plan guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) / [intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)).
|
|
|
|
- **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: `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 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](../configuration/settings) 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.
|
|
|
|
## 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` 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](../features/sandbox) 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.
|
|
|
|
## 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.
|
|
|
|
## Exit Codes
|
|
|
|
The Qwen Code uses specific exit codes to indicate the reason for termination. This is especially useful for scripting and automation.
|
|
|
|
| Exit Code | Error Type | Description |
|
|
| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
| 41 | `FatalAuthenticationError` | An error occurred during the authentication process. |
|
|
| 42 | `FatalInputError` | Invalid or missing input was provided to the CLI. (non-interactive mode only) |
|
|
| 44 | `FatalSandboxError` | An error occurred with the sandboxing environment (e.g. Docker, Podman, or Seatbelt). |
|
|
| 52 | `FatalConfigError` | A configuration file (`settings.json`) is invalid or contains errors. |
|
|
| 53 | `FatalTurnLimitedError` | The maximum number of conversational turns for the session was reached. (non-interactive mode only) |
|
|
|
|
## 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](https://github.com/QwenLM/qwen-code/issues). 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!
|