Skip to content

docs: document Node 26 fetch failed workaround #4301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
debpramanik wants to merge 1 commit into
base: main
Choose a base branch
from
+11 −1
Open

docs: document Node 26 fetch failed workaround #4301

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs/users/support/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This guide provides solutions to common issues and debugging tips, including top

- **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:
- **Solution:** Switch to a different authentication method. Run `qwen` -> `/auth` and choose one of:
Copy link
Copy Markdown
Collaborator

@wenshao wenshao May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Suggestion] Unrelated drive-by change: this line swaps → (unicode) for -> (ASCII), but the PR title/body only describe the Node.js v26 entry. The unicode → is the established convention in 20+ locations across docs/users/ (e.g. CLI → env → settings → defaults, Run qwen → /auth, Continue with Quickstart (5 mins) →). After this change, line 14 becomes the sole outlier in instructional prose.

Suggested: revert to → here, or — if the intent is to standardize on ASCII arrows — split that into a separate PR with a matching scope description.

Suggested change
- **Solution:** Switch to a different authentication method. Run `qwen` -> `/auth` and choose one of:
- **Solution:** Switch to a different authentication method. Run `qwen` → `/auth` and choose one of:

— qwen-latest-series-invite-beta-v28 via Qwen Code /review

- **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)).

Expand Down Expand Up @@ -51,6 +51,16 @@ This guide provides solutions to common issues and debugging tips, including top

## Common error messages and solutions

- **Error: `[API Error: Connection error. (cause: fetch failed)]` on every API call with Node.js v26.**
- **Cause:** Node.js v26 can be incompatible with the HTTP client path used by Qwen Code 0.15.11. In this case, Qwen Code may fail before it opens a network connection even when the same endpoint, model, and API key work with `curl` or a direct `node` `fetch()` request.
Copy link
Copy Markdown
Collaborator

@wenshao wenshao May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Suggestion] The hardcoded version pins "Qwen Code 0.15.11" and "Node.js v22.22.3 LTS" will become stale quickly. 0.15.11 is the only Qwen Code version pin anywhere in docs/; once 0.16+ ships (or once Node v26 itself becomes LTS), readers won't know whether the workaround still applies. .nvmrc already targets 22 (no patch) and engines says >=22.0.0, so v22.22.3 is unnecessary precision.

Consider version-agnostic phrasing plus a tracking link so future maintainers can tell whether the root cause is resolved:

Suggested change
- **Cause:** Node.js v26 can be incompatible with the HTTP client path used by Qwen Code 0.15.11. In this case, Qwen Code may fail before it opens a network connection even when the same endpoint, model, and API key work with `curl` or a direct `node` `fetch()` request.
- **Error: `[API Error: Connection error. (cause: fetch failed)]` on every API call with Node.js v26.**
- **Cause:** Node.js v26 can be incompatible with the HTTP client path used by Qwen Code (known to affect versions up to 0.15.11). In this case, Qwen Code may fail before it opens a network connection even when the same endpoint, model, and API key work with `curl` or a direct `node` `fetch()` request.
- **Solution:** Use a supported Node.js LTS release (v22.x). For example:
```bash
nvm install 22
nvm use 22
qwen -p "hi"
```
- **How to verify:** If the request works after switching Node.js versions, your base URL, model IDs, and API key were likely already correct; the Node.js runtime version was the blocker.

Note: Node.js v26 satisfies the >=22.0.0 engine requirement, so npm install succeeds without warning — the incompatibility only manifests at runtime. Consider mentioning this so users on v26 aren't surprised by a clean install followed by a runtime failure.

— qwen-latest-series-invite-beta-v28 via Qwen Code /review

- **Solution:** Use a supported Node.js LTS release. For example, downgrade from Node.js v26.0.0 to Node.js v22.22.3 LTS and retry the same Qwen Code configuration.
```bash
nvm install 22.22.3
nvm use 22.22.3
qwen -p "hi"
```
- **How to verify:** If the request works after switching Node.js versions, your base URL, model IDs, and API key were likely already correct; the Node.js runtime version was the blocker.

- **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:**
Expand Down
Loading