From 05fe1a05a86b3336c2c470fbd8d98d499f6c80c2 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Wed, 19 Aug 2026 08:27:31 -0700 Subject: [PATCH] Provide agent guidance on JSG_TRY vs. js.tryCatch The agents keep getting this wrong --- docs/reference/detail/legacy-module-registry.md | 2 +- src/workerd/jsg/AGENTS.md | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/reference/detail/legacy-module-registry.md b/docs/reference/detail/legacy-module-registry.md index 02e5788e1d1..0d383fe9d1b 100644 --- a/docs/reference/detail/legacy-module-registry.md +++ b/docs/reference/detail/legacy-module-registry.md @@ -216,7 +216,7 @@ Flow: 9. On not-found: retry with absolute path for `node:`/`cloudflare:` prefixed specifiers. 10. Final fallback: throw `"No such module"` error. -Errors are handled via `js.tryCatch`: exceptions are caught, and +Errors are handled via `JSG_TRY/JSG_CATCH`: exceptions are caught, and `js.v8Isolate->ThrowException()` is called to schedule them on the isolate (V8 requires exceptions to be scheduled, not thrown as C++ exceptions, during resolve callbacks). diff --git a/src/workerd/jsg/AGENTS.md b/src/workerd/jsg/AGENTS.md index 21e96964c43..d8b12b44335 100644 --- a/src/workerd/jsg/AGENTS.md +++ b/src/workerd/jsg/AGENTS.md @@ -62,6 +62,14 @@ class MyType: public jsg::Object { - `TypeHandler&` as trailing param gives manual conversion access - Compat flags param on `JSG_RESOURCE_TYPE` gates members conditionally +## Errors + +Use `JSG_TRY(js) { ... } JSG_CATCH(exception) { ... }` to catch JS exceptions in +C++ code. The `js` is a `jsg::Lock&` parameter. The `exception` is a `jsg::Value` +containing the JS exception that was thrown. + +The legacy `js.tryCatch(fn)` is deprecated and will be eventually removed. + ## ANTI-PATTERNS - **NEVER** opaque-wrap `V8Ref` — use handle directly