Introduce new CLIErrors and use them in the Wrangler type-generation src code

[dario-piotrowicz]

Introduce a new errors structure based on the abstract class CLIError each of this errors has a human and ai error message and displays the appropriate one based on who invoked Wrangler

These errors should be applied across all the Wrangler codebase but that would be a huge undertaking so as an expriment these are being just introduced and applied to the wrangler types logic (which is simple and self-contained enough)

---

To manually test this change you can run something like:

$ WRANGLER_OUTPUTS_FOR_AGENTS=true npx https://pkg.pr.new/wrangler@14574 types --env-interface="123bad"

to see the AI version of the invalid env interface name error

output

 ⛅️ wrangler 4.107.0 (dario/improved-error-messages)
────────────────────────────────────────────────────

✘ [ERROR] An error occurred, see the following details on how to handle it:

  ╭────────────────────────────────────────────────────────────────────────────────────────────╮
  │ ## Error: Invalid Env Interface Name                                                       │
  │                                                                                            │
  │ The env-interface value `123bad` is not a valid TypeScript identifier.                     │
  │                                                                                            │
  │ ### What happened                                                                          │
  │ The `--env-interface` option (or `envInterface` API option) specifies the name             │
  │ of the generated TypeScript interface for environment bindings. It must be a               │
  │ valid TypeScript identifier matching `/^[a-zA-Z][a-zA-Z0-9_]*$/`.                          │
  │                                                                                            │
  │ ### How to fix                                                                             │
  │ - Use a valid identifier: start with a letter, followed by letters, digits, or underscores │
  │ - Example: `wrangler types --env-interface=MyEnv`                                          │
  │ - If not specified, the default `Env` is used                                              │
  │                                                                                            │
  │ ### Question to ask the human                                                              │
  │ To better resolve this issue, consider asking the human developer the following:           │
  │ - What should the environment interface be named?                                          │
  ╰────────────────────────────────────────────────────────────────────────────────────────────╯


wrangler types [path]

📝 Generate types from your Worker configuration


POSITIONALS
  path  The path to the declaration file for the generated types  [string] [default: "worker-configuration.d.ts"]

GLOBAL FLAGS
  -c, --config          Path to Wrangler configuration file  [string]
      --cwd             Run as if Wrangler was started in the specified directory instead of the current working directory  [string]
  -e, --env             Environment to use for operations, and for selecting .env and .dev.vars files  [string]
      --env-file        Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files  [array]
  -h, --help            Show help  [boolean]
      --install-skills  Install Cloudflare skills for detected AI coding agents before running the command  [boolean] [default: false]
      --profile         Use a specific auth profile  [string]
  -v, --version         Show version number  [boolean]

OPTIONS
      --env-interface    The name of the generated environment interface  [string] [default: "Env"]
      --include-runtime  Include runtime types in the generated types  [boolean] [default: true]
      --include-env      Include Env types in the generated types  [boolean] [default: true]
      --strict-vars      Generate literal and union types for variables  [boolean] [default: true]
      --check            Check if the types at the provided path are up to date without regenerating them  [boolean]

📖 Learn more at https://developers.cloudflare.com/workers/languages/typescript/#generate-types
🪵  Logs were written to "/Users/dario/.wrangler/logs/wrangler-2026-07-06_16-11-08_310.log"

to see the human version run the following instead:

$ WRANGLER_OUTPUTS_FOR_AGENTS=false npx https://pkg.pr.new/wrangler@14574 types --env-interface="123bad"

output

 ⛅️ wrangler 4.107.0 (dario/improved-error-messages)
────────────────────────────────────────────────────

✘ [ERROR] The provided env-interface value ("123bad") does not satisfy the validation regex: /^[a-zA-Z][a-zA-Z0-9_]*$/


wrangler types [path]

📝 Generate types from your Worker configuration


POSITIONALS
  path  The path to the declaration file for the generated types  [string] [default: "worker-configuration.d.ts"]

GLOBAL FLAGS
  -c, --config          Path to Wrangler configuration file  [string]
      --cwd             Run as if Wrangler was started in the specified directory instead of the current working directory  [string]
  -e, --env             Environment to use for operations, and for selecting .env and .dev.vars files  [string]
      --env-file        Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files  [array]
  -h, --help            Show help  [boolean]
      --install-skills  Install Cloudflare skills for detected AI coding agents before running the command  [boolean] [default: false]
      --profile         Use a specific auth profile  [string]
  -v, --version         Show version number  [boolean]

OPTIONS
      --env-interface    The name of the generated environment interface  [string] [default: "Env"]
      --include-runtime  Include runtime types in the generated types  [boolean] [default: true]
      --include-env      Include Env types in the generated types  [boolean] [default: true]
      --strict-vars      Generate literal and union types for variables  [boolean] [default: true]
      --check            Check if the types at the provided path are up to date without regenerating them  [boolean]

📖 Learn more at https://developers.cloudflare.com/workers/languages/typescript/#generate-types
🪵  Logs were written to "/Users/dario/.wrangler/logs/wrangler-2026-07-06_16-12-50_658.log"

---

• 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: improved UX/AX

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 05fdabf

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

This PR includes changesets to release 3 packages

Name	Type
wrangler	Minor
@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]

Changeset Review

✅ All changesets look good

[pkg-pr-new]

@cloudflare/autoconfig

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

create-cloudflare

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

@cloudflare/deploy-helpers

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-auth

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: 05fdabf

[workers-devprod]

Codeowners approval required for this PR:

• @cloudflare/wrangler

Show detailed file reviewers

• .changeset/cli-errors-type-generation.md: [@cloudflare/wrangler]
• packages/workers-utils/src/environment-variables/factory.ts: [@cloudflare/wrangler]
• packages/wrangler/src/tests/cli-errors/cli-command-line-args-error.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/tests/cli-errors/cli-error.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/tests/core/handle-errors.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/tests/environment-detection.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/tests/metrics/sanitization.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/tests/type-generation.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/README.md: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/cli-command-line-args-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/cli-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/index.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/conflicting-binding-types-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/conflicting-types-file-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/deprecated-include-runtime-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/duplicate-interface-name-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/incompatible-service-worker-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/index.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/invalid-boolean-value-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/invalid-env-interface-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/invalid-output-path-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/missing-binding-field-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/missing-compatibility-date-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/missing-config-file-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/missing-environment-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/missing-pipeline-stream-id-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/missing-service-entry-point-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/missing-type-selection-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/no-generated-types-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/reserved-interface-name-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/runtime-types-fetch-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/types-file-not-found-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli-errors/type-generation/types-out-of-date-error.ts: [@cloudflare/wrangler]
• packages/wrangler/src/cli.ts: [@cloudflare/wrangler]
• packages/wrangler/src/core/handle-errors.ts: [@cloudflare/wrangler]
• packages/wrangler/src/core/register-yargs-command.ts: [@cloudflare/wrangler]
• packages/wrangler/src/environment-detection.ts: [@cloudflare/wrangler]
• packages/wrangler/src/metrics/sanitization.ts: [@cloudflare/wrangler]
• packages/wrangler/src/type-generation/helpers.ts: [@cloudflare/wrangler]
• packages/wrangler/src/type-generation/index.ts: [@cloudflare/wrangler]
• packages/wrangler/src/type-generation/pipeline-schema.ts: [@cloudflare/wrangler]
• packages/wrangler/src/type-generation/runtime/index.ts: [@cloudflare/wrangler]