[wrangler] Explain authentication required by remote bindings

[akim136]

Fixes #14798.

When local development starts bindings that need to run remotely, Wrangler now explains why Cloudflare authentication is required before showing the existing API token or OAuth recovery guidance.

It also maps the edge-preview API's 10405 response into the same friendly remote-session authentication error. This preserves the original error cause, telemetry message, and remediation steps. Tests cover all three observed API authentication codes and snapshot the API token and OAuth messages.

Risk: error-handling/message-only. No authentication or remote-binding behavior changes.

Validation:

• pnpm -w test:ci -F @cloudflare/remote-bindings — 5 files and 18 tests passed
• pnpm check — 197 tasks passed, including build, lint, formatting, typechecks, and type tests
• pnpm changeset status --since=upstream/main — Wrangler patch changeset detected

---

• Tests
  • Tests included/updated
• Public documentation
  • Cloudflare docs PR(s): N/A
  • Documentation not necessary because: This only clarifies an existing Wrangler error message.

[changeset-bot]

🦋 Changeset detected

Latest commit: dced430

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
wrangler	Patch
@cloudflare/vite-plugin	Patch
@cloudflare/vitest-pool-workers	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[allocsys]

Nice fix for the messaging! One gap I found while digging into #14798 that this PR doesn't cover yet: the handleUserFriendlyError() switch still only matches case 9106: case 10000:, so it won't catch the actual failure mode reported in the issue.

I ran a curl matrix directly against /accounts/{id}/workers/subdomain/edge-preview (the endpoint createPreviewSession() hits) with a few auth states:

• No Authorization header at all → code 9106 (already handled)
• Empty/garbage Authorization → code 9106 (already handled)
• A well-formed-but-invalid Bearer token → code 10405, "Method not allowed for this authentication scheme" (405) — not in the switch, falls through to default and dumps the raw APIError

The reason this matters for the reported bug specifically: requireAuth() (packages/workers-auth/src/core/factory.ts) can succeed purely from local cached state — getActiveAccountId() returns a cached id with no network call, and loginOrRefreshIfRequired() only checks local token expiry, never server-side revocation. So a stale/revoked token sails through requireAuth() and only gets validated for real when the edge-preview request goes out — which returns 10405, not 9106/10000.

So even with this PR's improved copy, a user with a stale/revoked token would still see the raw, unexplained APIError — the exact symptom in the original report — since it never reaches the code path that throws RemoteSessionAuthenticationError.

Suggest widening the switch to also catch 10405:

case 9106:
case 10000:
case 10405: {
  throw new RemoteSessionAuthenticationError(error);
}

Happy to share the repro workflow (live curl matrix + a small unit test suite covering this) if useful.

[akim136]

Great catch @allocsys! I’ve added 10405 to the remote-session authentication cases and covered it with an API error using HTTP 405. I kept the change scoped to remote-binding session errors rather than widening Wrangler’s global authentication classifier. The remote-bindings tests and repository checks pass.

[workers-devprod]

Codeowners reviews satisfied

[pkg-pr-new]

@cloudflare/autoconfig

npm i https://pkg.pr.new/@cloudflare/autoconfig@14806

@cloudflare/config

npm i https://pkg.pr.new/@cloudflare/config@14806

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@14806

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@14806

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@14806

miniflare

npm i https://pkg.pr.new/miniflare@14806

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@14806

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@14806

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@14806

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@14806

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@14806

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@14806

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@14806

wrangler

npm i https://pkg.pr.new/wrangler@14806

commit: dced430