error-handling

# Skill: Error Handling Every failure the library raises carries a machine-readable `code`. Consumers branch on the code; the message is for humans and may be reworded in any release. **Never make control flow depend on message text.** A regex over `e.message` is the exact failure this design exists to prevent. `src/core/error.ts` is the source of truth. `cpp/core/error.h` mirrors it **by hand**, the same way the rest of the TS/JSI interface is mirrored (DType definitions, schema types, host object interfaces). Nothing here is generated. If you add a code, add it in both files. --- ## 🚦 Throwing One factory, usable everywhere including inside worklets: ```typescript import { RnExecuTorchError } from '../../../core/error'; throw RnExecuTorchError('INVALID_ARGUMENT', `topk must be non-negative, got ${topk}`); ``` `RnExecuTorchError` is a function, not a class. Worklet runtimes are separate JavaScript runtimes and a value thrown on one does not keep its class identity or prototype chain when it travels to another, so a class would only survive some of the paths that throw. The factory returns a plain `Error` with `name`, `code`, and optionally `etRuntimeErrorCode` attached, which is exactly what crosses every boundary intact. Write messages the way the rest of the codebase does: prefix with the function name and include the offending values (`` `execute: Unknown method '${methodName}'` ``). The code says what class of problem it is; the message says which values caused it. --- ## 🎣 Catching `isRnExecuTorchError(err, code?)` narrows, and takes an optional code so you rarely need a second comparison: ```typescript import { isRnExecuTorchError } from '../core/error'; try { await classifier.classify(image); } catch (e) { if (isRnExecuTorchError(e, 'RESOURCE_BUSY')) return; // a run is already in flight throw e; } ``` It is duck-typed and marked `'worklet'`, so it works on both runtimes and on values that crossed the JSI boundary. --- ## 🔢 The Code Set ```text LOAD_FAILED EXECUTION_FAILED SCHEMA_MISMATCH INVALID_ARGUMENT INVALID_STATE RESOURCE_DISPOSED RESOURCE_BUSY DOWNLOAD_FAILED DOWNLOAD_ABORTED UNKNOWN ``` The set is deliberately coarse. **A distinct code earns its place only when an app can genuinely recover differently from it** (retry a download, wait for a busy resource, re-create a disposed one). Everything else is a category that exists so crash reporters can group failures, and the detail belongs in the message. Concretely: do not add a code for a specific subsystem (a tokenizer failure is `EXECUTION_FAILED` or `LOAD_FAILED`) or for a variant of "the caller got it wrong" (`INVALID_ARGUMENT` already covers unsupported languages, bad ranges, and wrong types). Subdividing non-recoverable failures buys nothing over the message. Adding one means editing `VALID_ERROR_CODES` in `src/core/error.ts` **and** adding a single line to `FOR_ALL_RNEXECUTORCH_ERROR_CODES` in `cpp/core/error.h`. That X-macro list expands into the enum, the string mapping, and the factory functions at once, so the three cannot drift apart. --- ## ⚙️ C++ / JSI Two rules, both mandatory: 1. **Never throw `jsi::JSError` from library code.** Throw through a factory, which builds an `RnExecuTorchException`. `guarded` is the only place that turns an exception into a JavaScript value, so a code cannot be lost on the way out. 2. **Wrap every host function registration in `error::guarded(...)`.** Without it the code is lost, including on the synchronous worklet path that VisionCamera frame processors use, which has no `wrapAsync` fallback. There is one factory per code, so a throw site names the code and nothing else: ```cpp #include "core/error.h" namespace rnexecutorch::extensions::<domain> { namespace jsi = facebook::jsi; // Required in extensions::*, where sibling lookup does not reach core. // OMIT this alias inside rnexecutorch::core::*, where unqualified `error` // already resolves to rnexecutorch::core::error (clang-tidy fails on a dead alias). namespace error = rnexecutorch::core::error; void install_customOp(jsi::Runtime &rt, jsi::Object &module) { const auto *name = "customOp"; auto fnBody = [](jsi::Runtime &rt, const jsi::Value & /*thisVal*/, const jsi::Value *args, size_t count) -> jsi::Value { if (count != 3) { throw error::InvalidArgument("customOp: Usage: customOp(src, dst, factor)"); } // ... return jsi::Value(rt, args[1]); }; module.setProperty(rt, name, jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, name), 3, error::guarded(fnBody))); } } // namespace ``` The alias is the only preamble a file needs. Name `RnExecuTorchException` or `RnExecuTorchErrorCode` directly **only** where you genuinely need the type: a `catch` clause, or a helper that takes a code as a parameter (see `unwrap` in `cpp/core/model.cpp`). Every factory takes an optional second argument, an `executorch::runtime::Error`, which travels to JS as `etRuntimeErrorCode` for diagnostics: `error::ExecutionFailed(msg, result.error())`. Pass it only when the failure really came out of the ExecuTorch runtime. Unwrapping an ExecuTorch `Result` is done with a small file-local `unwrap` helper (see `cpp/core/model.cpp`), not a shared utility. `guard` deliberately lets an existing `jsi::JSError` pass through untouched, so an error thrown by an app's own callback (for example inside `tensor.through(fn)`) is never rewritten with our name and code. **Placement warning:** put `#include "core/error.h"` and the namespace alias at file scope, never inside an `#if defined(__ANDROID__)` / `#elif defined(__APPLE__)` branch. Code inside a platform branch compiles on your machine and breaks on every other target, and a macOS-only local syntax check will not catch it. --- ## 📱 Example Apps Leave error handling in `apps/` alone. They are a testing ground, so failures should be surfaced raw (`e.message`, `String(e)`) rather than translated into friendly copy. See issue #1288 for the separate discussion about splitting user-facing examples out. --- ## 🚫 Avoid / Anti-Patterns - **Do NOT branch on message text.** No `/disposed/i.test(msg)`, no `msg.includes(...)`. Use the code. - **Do NOT throw bare `Error` or `jsi::JSError`** from library code. - **Do NOT make `RnExecuTorchError` a class.** It has to survive worklet boundaries. - **Do NOT add a code for a failure an app cannot recover from differently.** Enrich the message instead. - **Do NOT mirror the TS codes with a code generator.** The C++ side is written by hand, like the rest of the TS/JSI interface. The X-macro inside `error.h` is not codegen: it keeps three C++ declarations of one list in step, it does not read the TypeScript. - **Do NOT leave a stale `@throws`.** Doc comments naming `jsi::JSError`, `std::runtime_error`, or `std::invalid_argument` are wrong: nothing in the library throws those any more. --- ## 📋 Verification Checklist When adding or changing error handling, verify that: - [ ] Every new throw site uses `RnExecuTorchError('CODE', message)` (TS) or `error::Code(message)` (C++). - [ ] No raw `jsi::JSError` / `std::runtime_error` / `std::invalid_argument` was introduced. - [ ] Every new `createFromHostFunction` registration is wrapped in `error::guarded(...)`. - [ ] The `namespace error = ...` alias is present in `extensions::*` and absent in `core::*`. - [ ] `#include "core/error.h"` and the `namespace error = ...` alias sit at file scope, outside any preprocessor branch. - [ ] `RnExecuTorchException` / `RnExecuTorchErrorCode` are named only in a `catch` clause or a helper taking a code, never at a throw site. - [ ] Catch sites use `isRnExecuTorchError(e, 'CODE')` rather than matching on the message. - [ ] Every `@throws` on a function you touched names the exception **and its code** (`@throws error::RnExecuTorchException with code InvalidArgument if ...` in C++, `@throws {RnExecuTorchError} With code \`INVALID_ARGUMENT\` if ...` in TypeScript). - [ ] Any new code was justified by a distinct recovery path, and added to `src/core/error.ts` **and** `cpp/core/error.h` (enum + `errorCodeToString`). - [ ] Error handling in `apps/` was left surfacing raw errors.