🐛 BUG: TOML not validated before running Worker + bad Browser Rendering API error

[irvinebroque]

Which Cloudflare product(s) does this pertain to?

Wrangler

What version(s) of the tool(s) are you using?

3.95.0

What version of Node are you using?

22.3.0

What operating system and version are you using?

Sequoia 15.1.1

Describe the Bug

This TOML:

name = "browser-rendering-remote"
main = "src/index.js"
compatibility_date = "2024-12-05"
compatibility_flags = ["nodejs_compat"]

[observability]
enabled = true

browser = { binding = "MYBROWSER" }

...allows you to run a Worker, but then at runtime, try wrangler dev --remote and you'll see the following runtime error:

[wrangler:inf] GET /favicon.ico 500 Internal Server Error (51ms)
✘ [ERROR] Uncaught (in response) TypeError: Cannot read properties of undefined (reading 'fetch')

      at PuppeteerWorkers.launch
  (file:///Users/brendan/src/test/browser-rendering-remote/.wrangler/tmp/dev-na2A11/index.js:16857:32)
      at Object.fetch
  (file:///Users/brendan/src/test/browser-rendering-remote/.wrangler/tmp/dev-na2A11/index.js:18456:56)
      at fetchDispatcher
  (file:///Users/brendan/src/test/browser-rendering-remote/.wrangler/tmp/dev-na2A11/index.js:18554:19)
      at __facade_invokeChain__
  (file:///Users/brendan/src/test/browser-rendering-remote/.wrangler/tmp/dev-na2A11/index.js:18516:10)

The browser property above is interpreted as a part of [observability] — even though [observability] has no such property that one can configure.

The browser binding is not defined at runtime, leading to the runtime error.

This is likely to happen a lot because the C3 template we give you back uses []:

workers-sdk/packages/create-cloudflare/templates-experimental/remix/templates/wrangler.toml

Lines 9 to 11 in 0117820

	# Configuration: https://developers.cloudflare.com/workers/observability/logs/workers-logs/#enable-workers-logs
	[observability]
	enabled = true

so if you drop browser = { binding = "MYBROWSER" } (or similar) under this, then you'll hit some flavor of this issue. And it looks like things are breaking at runtime, which is horribly misleading.

What do we need to do?

1. Use TOML syntax that is less likely to cause confusing errors cloudflare-docs#18706 — we should give people example TOML that is less prone to this footgun
2. We should consider starting to loudly raise a warning (not error) in local dev if we see properties within wrangler.toml that we know are not supported as part of the given binding/thing being configured. Ex: if I see that the observability binding has a browser property configured — we should know that that....isn't a thing and warn you — right?
3. We should likely audit docs for other examples of places where we can do (1)
4. In the Browser Rendering puppeteer fork, we should be able to check if the binding was actually passed in — and if not, throw a loud and clear error that explains
5. Anything else?

Please provide a link to a minimal reproduction

https://github.com/irvinebroque/browser-rendering-remote

h/t @rita3ko finding this

[irvinebroque]

@lrapoport-cf recognize one answer to this is — wrangler.json

We also have lot of people using TOML.

If I understand root cause right — seems like there should be a way to validate / warn about fields that we see in TOML config that aren't actually part of that thing? So that we can give people better guidance?

@nevikashah re: footgun getting started

[penalosa]

This is definitely a footgun with TOML syntax (and as you say, mitigated by docs and wrangler.json). That said, I thought we did have validation warnings for additional unknown properties set up, which should've warned in this case.

cc @Ankcorn looks like we might not have validateAdditionalProperties working for observability?

[penalosa]

Having tried this out a bit more, I can't seem to reproduce this. When I run the latest Wrangler against your repro config file I get this output, which includes a loud warning:

 ⛅️ wrangler 3.95.0
-------------------

▲ [WARNING] Processing wrangler.toml configuration:

    - Unexpected fields found in observability field: "browser"


[wrangler:inf] Ready on http://localhost:8787
⎔ Starting remote preview...
Total Upload: 607.40 KiB / gzip: 117.98 KiB

@irvinebroque do you have a debug log for your Wrangler run/could you re-run with WRANGLER_LOG=debug to try and help diagnose why the warning isn't being shown in your case?

[irvinebroque]

You're right, sounds like we fixed this at some point between Wrangler 3.6 and 3.96

 ⛅️ wrangler 3.96.0
-------------------

▲ [WARNING] Processing wrangler.toml configuration:

    - Unexpected fields found in observability field: "browser"

Looking into how I had project that was Wrangler 3.6