Improve error messages for Pages CLI commands

[dario-piotrowicz]

Error messages across wrangler pages subcommands (deploy, dev, secret, project, etc.) now provide clearer descriptions and actionable guidance. For example, instead of "Must specify a project name.", you'll now see "Missing Pages project name. Use --project-name or set the name in your wrangler.jsonc configuration file."

Input validation errors also now use UserError instead of FatalError for more accurate error classification.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: just improving some error messages

A picture of a cute animal (not mandatory, but encouraged)

[changeset-bot]

🦋 Changeset detected

Latest commit: e3e9294

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

[github-actions]

✅ All changesets look good

[ask-bonk]

The review was posted successfully. Here's a summary of what I found:

Two issues identified on PR #14010:

1. Broken test indentation in secret.test.ts — The "should error with invalid env" and "should error without a project name" test blocks were accidentally dedented, breaking the describe nesting structure. They moved from 3-tab depth (inside the describe("put") block) to 2-tab depth, which changes test scoping.

2. Hardcoded wrangler.jsonc in deploy.ts line 361 — The error message references wrangler.jsonc specifically, but users might be using wrangler.toml or wrangler.json. The other identical error in the same file (line 280) correctly uses the generic "your Wrangler configuration file" phrasing. I posted a suggestion to fix this.

github run

[pkg-pr-new]

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: e3e9294

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[devin-ai-integration]

Devin Review found 1 potential issue.

View 3 additional findings in Devin Review.

[workers-devprod]

Codeowners reviews satisfied