fix(proxy): surface upstream error cause and distinguish timeouts

[harlan-zw]

🔗 Linked issue

Resolves#756

❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

Proxy upstream failures previously threw a bare 502 with no cause, making it impossible to tell a real upstream error from the 15s abort timeout. Now the original error is attached as cause, errorName/errorCode are exposed in H3Error.data, and timeouts return 504 Gateway Timeout instead of 502.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview, Comment	May 8, 2026 4:40am

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@757

commit: 8f5533f

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7f6c724d-ce04-4e35-92eb-af6ec35645eb

📥 Commits

Reviewing files that changed from the base of the PR and between ceb4ba0 and 0e57f50.

📒 Files selected for processing (1)

• packages/script/src/runtime/server/proxy-handler.ts

---

📝 Walkthrough

Walkthrough

The proxy handler now explicitly tracks upstream fetch timeouts using a timedOut boolean flag set by a 15-second AbortController timeout callback. When upstream requests fail, error responses are now conditional: requests that timed out return 504 Gateway Timeout with errorCode: TIMEOUT, while other failures return 502 Bad Gateway. The createError call now includes the underlying error as a cause and enriches data with the error's name and an appropriate errorCode, making timeout failures distinguishable from connection resets and other network errors.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: improving error handling in the proxy by surfacing upstream error cause and distinguishing timeout errors from other upstream failures.
Description check	✅ Passed	The description is well-related to the changeset, explaining the problem (missing error cause), the solution (attaching cause and errorCode), and the outcome (504 for timeouts vs 502 for other failures).
Linked Issues check	✅ Passed	The PR fully addresses issue #756 by attaching the original error as cause, exposing errorName/errorCode in H3Error.data, and returning 504 for timeouts vs 502 for upstream failures.
Out of Scope Changes check	✅ Passed	All changes in proxy-handler.ts are directly related to the stated objectives of improving error handling and distinguishing timeouts, with no extraneous modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/proxy-timeout-status

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}