Codestin Search App

chrisdavidmills · 2026-05-06T15:13:26Z

Description

This PR adds documentation for "modern" WebAssembly Exception handling. I am not intending to document "legacy" Wasm exception handling alongside this, as it would make the documentation significantly more complex (some features are used in both), and I'm sure we want to encourage devs to use the modern version.

Specifically, this PR documents the following:

I am also going to check whether the following, already existing, ref docs need any updates:

WebAssembly.Tag and members
WebAssembly.Exception and members

I have also added a page for WebAssembly.JSTag

Motivation

Additional details

Related issues and pull requests

github-actions · 2026-05-06T15:15:16Z

Preview URLs (30 pages)

Flaws (1)

Note! 29 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/WebAssembly/Reference/JavaScript_interface/Tag
Title: WebAssembly.Tag
Flaw count: 1

broken_links:
- Link /en-US/docs/WebAssembly/Reference/Types/exnref doesn't resolve

(comment last updated: 2026-05-22 18:51:07)

eqrion

This is looking good. There's one missing piece (described below). And a possibly structural change around try_table.

One missing piece is the WebAssembly.JSTag global [1]. It's a special WebAssembly.Tag on the WebAssembly namespace. The type is (tag (param externref))

Any thrown JS value that is caught by wasm is automatically wrapped in an exception with the JSTag. This allows wasm to import the JSTag and then catch JS exceptions.
If wasm throws an exception with JSTag and JS catches it, then the wrapped externref value in exception is caught, not a WebAssembly.Exception object.

[1] https://www.w3.org/TR/wasm-js-api-2/#dom-webassembly-jstag

eqrion · 2026-05-15T21:08:44Z

+  - : One or more `catch` clauses, each representing criteria for catching exceptions, and specifying a [`block`](/en-US/docs/WebAssembly/Reference/Control_flow/block) to branch to as a result. Each clause can be one of the following instructions:
+    - [`catch`](/en-US/docs/WebAssembly/Reference/Exception_handling/catch)
+    - [`catch_all`](/en-US/docs/WebAssembly/Reference/Exception_handling/catch_all)
+    - [`catch_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/catch_ref)
+    - [`catch_all_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/catch_all_ref)


Technically these are not actually instructions. They can only ever be used as part of a try_table instruction, and so they're essentially a part of the syntax of the instruction.

Is it possible to merge them into this page?

This makes sense, although I wonder whether this might make the page a bit long and unwieldy. What do you think of the idea of making them subpages of the try_table page?

If they are not instructions, what should I refer to them as?

Sub pages makes sense to me. You could maybe refer to them as catch clauses? I think the technical term is 'instruction immediate' because it's an inherent part of the try_table instruction (sort of like how the 32 is part of i32.const 32, or $label in br $label). But catch clause is the more common term.

@eqrion OK, I've restructured the pages so that the catch clauses are now subpages of try_table, and are referred to as clauses everywhere, not instructions.

eqrion · 2026-05-15T21:12:43Z

+## Syntax
+
+```plain
+try_table catch* instruction*


Suggested change

try_table catch* instruction*

try_table blocktype? catch* instruction*

A try_table can have a blocktype which specifies what params and results it takes (all wasm blocks block loop if are like this)

So you could have:

;; push an i32 i32.const 42 ;; pops an i32 as the param try_table (param i32) ;; the single i32 const 42 is still on the stack end

Or:

try_table (result i32) ;; push an i32 i32.const 42 ;; the end of the block pops the results end ;; the result i32 is now available to be used here

Or any combination.

Cool, I missed that. I've had a go at adding the details, including a syntax addition, and a section covering it in the description. I'm guessing some more details might be needed, but let me know what you think.

I also wonder if we should provide an example in the Examples section.

…ex.md Co-authored-by: Ryan Hunt <[email protected]>

chrisdavidmills · 2026-05-16T19:03:15Z

@caugner @LeoMcA the WebAssembly.JSTag page I've added in this PR is not showing up in the generated sidebar, at least, not in the local environment. What can I do about this? Should I file a bug on the fred repo?

caugner · 2026-05-16T21:41:01Z

@chrisdavidmills The sidebar is defined in https://github.com/mdn/content/blob/main/files/sidebars/webassemblysidebar.yaml, but if there's a section that should cover this, then don't hesitate to file a Rari issue.

chrisdavidmills · 2026-05-17T08:53:25Z

@chrisdavidmills The sidebar is defined in https://github.com/mdn/content/blob/main/files/sidebars/webassemblysidebar.yaml, but if there's a section that should cover this, then don't hesitate to file a Rari issue.

@caugner yeah, I'm pretty sure that the page in question should be picked up and included in the sidebar section generated by https://github.com/mdn/content/blob/main/files/sidebars/webassemblysidebar.yaml#L47, but it doesn't.

I'll file a rari issue about it.

chrisdavidmills · 2026-05-17T09:03:43Z

I'll file a rari issue about it.

mdn/rari#703

eqrion · 2026-05-18T21:41:03Z

I've also added one-line definitions of the basic numeric types to the Types page, so that they are represented. I don't think they need their own pages, but let me know if you think differently.

@chrisdavidmills I haven't had a chance to look at the full PR again. But on Friday I quickly whipped up some pages for the primitive value types and function types (#44181). I think it'd be a good idea to have them documented.

chrisdavidmills · 2026-05-19T18:39:33Z

I've also added one-line definitions of the basic numeric types to the Types page, so that they are represented. I don't think they need their own pages, but let me know if you think differently.

@chrisdavidmills I haven't had a chance to look at the full PR again. But on Friday I quickly whipped up some pages for the primitive value types and function types (#44181). I think it'd be a good idea to have them documented.

Your PR is looking great; I've provided a review. We should get that one merged before we go too much further on this PR, but I'll at least get the catch clauses reorganization done now.

caugner

Front matter config change LGTM.

github-actions · 2026-05-21T08:17:38Z

This pull request has merge conflicts that must be resolved before it can be merged.

…xception-handling

chrisdavidmills · 2026-05-21T08:45:55Z

@caugner can I get some help with this set of merge conflicts? I'm unable to pull them to my local branch to resolve them. No matter what I do, it keeps telling me my local branch is up to date.

caugner · 2026-05-21T09:43:54Z

@caugner can I get some help with this set of merge conflicts? I'm unable to pull them to my local branch to resolve them.

It looks like #44181 removed the WebAssembly/Reference/Types page with a redirect to WebAssembly/Reference/Value_types, but this PR here updated that page.

To resolve the conflict, you'll want to remove that page in your branch as well, and potentially replicate your changes to WebAssembly/Reference/Value_types.

No matter what I do, it keeps telling me my local branch is up to date.

That sounds like your main is not up to date with upstream (although your fork's main is up to date). So if I were you I would switch to your local main, and run git pull, then switch back to this branch (shortcut: git checkout -), then try git merge main again.

eqrion

LGTM from a technical perspective.

eqrion · 2026-05-21T14:14:48Z

+The `exnref` type represents a thrown exception in a Wasm module. This value type is returned by the [`catch_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/try_table/catch_ref) and [`catch_all_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/try_table/catch_all_ref) clauses, providing a reference to the exception that was just thrown, and allowing it to be rethrown if required using the [`throw_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/throw_ref) instruction.
+
+The [`WebAssembly.Exception`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Exception) JavaScript interface represents a Wasm exception in the JavaScript host.
+


One extra thing worth noting is that you are not permitted to call a wasm function from JS that has 'exnref' as a parameter or result. This is the same kind of restriction as v128.

I've added the note. I've also updated all the value type page titles from "Wasm type" to "Wasm value type".

chrisdavidmills · 2026-05-22T18:34:47Z

@caugner can I get some help with this set of merge conflicts? I'm unable to pull them to my local branch to resolve them.

It looks like #44181 removed the WebAssembly/Reference/Types page with a redirect to WebAssembly/Reference/Value_types, but this PR here updated that page.

To resolve the conflict, you'll want to remove that page in your branch as well, and potentially replicate your changes to WebAssembly/Reference/Value_types.

No matter what I do, it keeps telling me my local branch is up to date.

That sounds like your main is not up to date with upstream (although your fork's main is up to date). So if I were you I would switch to your local main, and run git pull, then switch back to this branch (shortcut: git checkout -), then try git merge main again.

Cool, thanks @caugner! I think I got it sorted ;-)

Document Wasm exception handling

54d813a

chrisdavidmills requested a review from a team as a code owner May 6, 2026 15:13

chrisdavidmills requested review from hamishwillee and removed request for a team May 6, 2026 15:13

chrisdavidmills marked this pull request as draft May 6, 2026 15:13

github-actions Bot added Content:wasm WebAssembly docs size/m [PR only] 51-500 LoC changed labels May 6, 2026

chrisdavidmills added 3 commits May 11, 2026 19:23

document exnref type

8e40c96

Merge branch 'main' into wasm-exception-handling

38921ef

Add throw ref page, correct errors

2b60911

github-actions Bot added size/l [PR only] 501-1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels May 13, 2026

chrisdavidmills added 3 commits May 13, 2026 15:01

Add throw_ref ref page

30e02b8

Add try_table ref page

567c828

Add catch instruction ref page

6dc5f6a

github-actions Bot added size/xl [PR only] >1000 LoC changed and removed size/l [PR only] 501-1000 LoC changed labels May 14, 2026

chrisdavidmills added 5 commits May 14, 2026 13:28

Add catch_ref instruction ref page

ce9e3a3

Add catch_all instruction ref page

585cc8a

Add catch_all_ref instruction ref page

11878a0

Check WebAssembly.Tag JSAPI and make updates

843adde

Check WebAssembly.Exception JSAPI and make updates

eebf36b

chrisdavidmills marked this pull request as ready for review May 14, 2026 18:47

chrisdavidmills requested a review from a team as a code owner May 14, 2026 18:47

chrisdavidmills requested review from pepelsbey and removed request for a team May 14, 2026 18:47

chrisdavidmills changed the title ~~Document Wasm exception handling~~ Technical review: Document Wasm exception handling May 14, 2026

eqrion reviewed May 15, 2026

View reviewed changes

Update files/en-us/webassembly/reference/exception_handling/throw/ind…

b6c01fa

…ex.md Co-authored-by: Ryan Hunt <[email protected]>

chrisdavidmills requested a review from eqrion May 16, 2026 18:56

chrisdavidmills mentioned this pull request May 17, 2026

New WebAssembly static property page not showing up in generated sidebar section mdn/rari#703

Closed

eqrion mentioned this pull request May 18, 2026

[wasm] Split value types and type definitions #44181

Merged

chrisdavidmills added 3 commits May 19, 2026 19:40

Merge branch 'main' into wasm-exception-handling

e6abfa7

Move catch clauses to subpages

b2548ea

Get JSTag to display in sidebar

c896d10

chrisdavidmills requested a review from a team as a code owner May 19, 2026 20:59

chrisdavidmills requested review from caugner and removed request for a team and eqrion May 19, 2026 20:59

github-actions Bot added the system [PR only] Infrastructure and configuration for the project label May 19, 2026

caugner approved these changes May 19, 2026

View reviewed changes

github-actions Bot added the merge conflicts 🚧 [PR only] label May 21, 2026

Merge branch 'main' of github.com:chrisdavidmills/content into wasm-e…

dbbd8fe

…xception-handling

eqrion reviewed May 21, 2026

View reviewed changes

Sort merge conflicts

68dfc78

github-actions Bot removed the merge conflicts 🚧 [PR only] label May 22, 2026

Add exnref note and value type titles

b0a6766

chrisdavidmills merged commit 48b0dc4 into mdn:main May 22, 2026
11 checks passed

chrisdavidmills deleted the wasm-exception-handling branch May 22, 2026 18:52

	try_table catch* instruction*
	try_table blocktype? catch* instruction*

		The `exnref` type represents a thrown exception in a Wasm module. This value type is returned by the [`catch_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/try_table/catch_ref) and [`catch_all_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/try_table/catch_all_ref) clauses, providing a reference to the exception that was just thrown, and allowing it to be rethrown if required using the [`throw_ref`](/en-US/docs/WebAssembly/Reference/Exception_handling/throw_ref) instruction.

		The [`WebAssembly.Exception`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Exception) JavaScript interface represents a Wasm exception in the JavaScript host.

Conversation

chrisdavidmills commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eqrion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chrisdavidmills commented May 16, 2026

Uh oh!

caugner commented May 16, 2026

Uh oh!

chrisdavidmills commented May 17, 2026

Uh oh!

chrisdavidmills commented May 17, 2026

Uh oh!

eqrion commented May 18, 2026

Uh oh!

chrisdavidmills commented May 19, 2026

Uh oh!

caugner left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 21, 2026

Uh oh!

chrisdavidmills commented May 21, 2026

Uh oh!

caugner commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eqrion left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills commented May 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

chrisdavidmills commented May 6, 2026 •

edited

Loading

github-actions Bot commented May 6, 2026 •

edited

Loading

caugner commented May 21, 2026 •

edited

Loading