[wrangler] Add upgrade hint to unexpected configuration field warnings by southpolesteve · Pull Request #11800 · cloudflare/workers-sdk

southpolesteve · 2026-01-05T22:48:47Z

Summary

When Wrangler encounters unexpected fields in the configuration file, users often don't know why. This PR improves the warning message to suggest updating Wrangler as a potential solution, since the field might be valid in a newer version.

Before:

▲ [WARNING] Processing wrangler.jsonc configuration:
    - Unexpected fields found in observability field: "tracing"

After:

▲ [WARNING] Processing wrangler.jsonc configuration:
    - Unexpected fields found in observability field: "tracing"
      If this is a new configuration option, please update your Wrangler version.

Tests
- Tests included/updated
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: This is an improvement to an existing warning message

When Wrangler encounters unexpected fields in the configuration file, it now suggests updating Wrangler as a potential solution. This helps users who may be using configuration options that were added in a newer version of Wrangler.

changeset-bot · 2026-01-05T22:48:51Z

🦋 Changeset detected

Latest commit: a8ceb52

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

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

claude · 2026-01-05T22:49:12Z

Claude finished @southpolesteve's task —— View job

Changeset Review

✅ All changesets look good

The changeset .changeset/unexpected-fields-upgrade-hint.md has been reviewed and validated:

✅ Version Type: Correctly uses patch for this bug fix/improvement to warning messages
✅ Changelog Quality: Clear title and informative description explaining the change and its purpose
✅ Markdown Headers: No h1/h2/h3 headers present (follows formatting rules)
✅ Package Coverage: Correctly references only wrangler package

The changeset follows all guidelines from .changeset/README.md.

pkg-pr-new · 2026-01-05T22:52:52Z

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: a8ceb52

When there are unexpected field warnings, also log the current wrangler version and the latest available version (if an update is available). This helps users know if they're behind and should upgrade.

Instead of using void with an async function (which could print after other output or not at all), use a synchronous getter that returns the cached latest version if the update check has already completed. This is reliable because the banner kicks off the update check early.

packages/wrangler/src/update-check.ts

packages/wrangler/src/config/index.ts

packages/workers-utils/src/config/validation-helpers.ts

vicb

I don't find "If this is a new configuration option, please update your Wrangler version." helpful.

i.e. what if not?

It could be a typo, you could already be on the latest wrangler, ...

Maybe one thing we could do instead is to validate the config against the schema and error early?

southpolesteve · 2026-01-06T14:53:58Z

I don't find "If this is a new configuration option, please update your Wrangler version." helpful.

Alternative suggestions? Something needs to change about the current error. Its a dead end. Not clear what the fix is and we should at least guide the user in some direction. It could be other things but suggesting upgrading wrangler is not an unhelpful suggestion.

The wrangler banner already shows '(update available X.X.X)' when a newer version exists. Adding version info after the warning was redundant. Keep only the simple hint message in the warning itself.

The indentText function in diagnostics.ts already adds 2 spaces to continuation lines, so the source message should not have leading spaces. This fixes the CI test failure.

vicb · 2026-01-06T19:02:58Z

I don't find "If this is a new configuration option, please update your Wrangler version." helpful.

Alternative suggestions? Something needs to change about the current error. Its a dead end. Not clear what the fix is and we should at least guide the user in some direction. It could be other things but suggesting upgrading wrangler is not an unhelpful suggestion.

My alternative suggestion would be to validate the config against the schema and error if there is a mismatch.

IMO we should not "please update your Wrangler version" because this might not solve the issue and adding more code (that has to be maintained) for something that is not very helpful is a burden.

vicb · 2026-01-06T19:04:29Z

Looking at the diffs:

					    - Unexpected fields found in migrations field: \\"unrecognized_field\\"
					      If this is a new configuration option, please update your Wrangler version."

This PR is only adding noise here

Instead of always showing the upgrade hint for unexpected config fields, only display it when we detect that a newer version of Wrangler exists. This avoids confusing users who are already on the latest version.

petebacondarwin

I think the idea of putting up a message (especially as it only happens once and only if there is a newer version of Wrangler available) is a reasonable UX improvement.

I think the message can be better - I made a suggestion.
But also I think we could/should look at doing some kind of fuzzy matching on the unexpected option like:

"Unexpected option trcing, did you mean tracing?"

petebacondarwin · 2026-01-07T10:10:01Z

packages/wrangler/src/config/index.ts

 		logger.warn(diagnostics.renderWarnings());
+
+		// If there are unexpected field warnings and an update is available, suggest upgrading
+		if (diagnostics.renderWarnings().includes("Unexpected fields found")) {


This is a fragile check, what if we tweak the message?
I think it would be better to change the config validation so that it returns a flag or something when an unexpected field is found. Then check that instead.

See my earlier comment

I think it would be better to change the config validation so that it returns a flag or something when an unexpected field is found. Then check that instead.

As discussed here and on offline channels, I think the long term fix is to use the schema and drop the hand written validation code so that we have a single exhaustive source of truth.

petebacondarwin · 2026-01-07T10:11:39Z

packages/wrangler/src/config/index.ts

+	const latestVersion = await updateCheck();
+	if (latestVersion !== undefined) {
+		logger.log(
+			`If this is a new configuration option, consider updating Wrangler. ` +


What does "new" mean? If they are on a really old version of Wrangler then the option might not be new in any reasonable sense.

Instead I would propose that we say something more like:

"There is a newer version of Wrangler available. Try upgrading as this might support the unexpected option."

petebacondarwin · 2026-03-14T17:43:29Z

Triage notes (stale PR review)

The core idea (showing an upgrade hint when unexpected config fields are found) is sound, but the implementation needs rework per review feedback from @petebacondarwin and @vicb.

Required changes:

Replace magic string matching with a structured flag - Instead of diagnostics.renderWarnings().includes("Unexpected fields found"), add a hasUnexpectedFields boolean to the Diagnostics class in @cloudflare/workers-utils. Set it to true when unknown fields are encountered during validation.
Reword the message - Per Pete's suggestion: "There is a newer version of Wrangler available (current: X.Y.Z, latest: A.B.C). Try upgrading, as it might support this configuration option."
De-duplicate with the banner - The Wrangler banner already shows "(update available X.Y.Z)". Either only show the hint when the banner doesn't appear, or clearly differentiate it as contextual advice.
Extract shared helper - Don't copy-paste the check+hint block between readConfig and readPagesConfig.
Resolve merge conflicts - PR is in CONFLICTING state.

Estimated effort: ~2-3 hours

southpolesteve requested a review from a team as a code owner January 5, 2026 22:48

workers-devprod added this to workers-sdk Jan 5, 2026

github-project-automation bot moved this to Untriaged in workers-sdk Jan 5, 2026

southpolesteve added 2 commits January 5, 2026 21:08

Show current and latest version when unexpected fields are found

45d6c90

When there are unexpected field warnings, also log the current wrangler version and the latest available version (if an update is available). This helps users know if they're behind and should upgrade.