RFC: Unified, web-compliant error handling — WinterTC-aligned events, nativeuncaughterror, stackTrace legacy status, and runtime-free error UI

[edusperoni]

RFC: Unified, web-compliant error handling — WinterTC-aligned events, nativeuncaughterror, stackTrace legacy status, and runtime-free error UI

Status	Proposed
Target	NativeScript 9.1 (contract), NativeScript 10 (removals)
Related	ios#409 · android#1985 · iOS docs: error-handling.md

Summary

NativeScript 9.1 unifies error handling across the iOS and Android runtimes around the web's model, on top of a standards-aligned event foundation: spec-shaped Event/EventTarget as general-purpose global primitives, ErrorEvent/PromiseRejectionEvent, reportError(), and cancelable error / unhandledrejection (+ rejectionhandled) events on globalThis — the same surface WinterTC (TC55, Minimum Common Web Platform API) standardizes for non-browser runtimes — plus the native-interop extensions the web has no vocabulary for: a shared uncaughtErrorPolicy config, interop.escapeException, and native exceptions round-tripping with their original identity.

This RFC (a) documents that foundation as the shared contract both runtime PRs implement, and (b) proposes the three remaining contract decisions before 9.1 freezes them:

1. Ratify the nativeuncaughterror event (landed on Android in 17cd448; proposed for iOS) — a last-chance, cancelable event fired when the platform's uncaught-exception handler sees a native-layer death the JS pipeline never reported. preventDefault() skips the platform's default behavior (dev error UI + the default killing handler) on a best-effort basis. This completes the invariant that error/unhandledrejection fire only while the failure is still containable.
2. Classify error.stackTrace as hook-era legacy — canonical stack sources in the events contract are error.stack (JS) and error.nativeException (native); the injected stackTrace property stays for compatibility but does not become part of the forever-spec.
3. Move error presentation (iOS error modal / Android error activity) out of the runtimes — the runtimes report through events; core (or userland) owns the UI as a default error listener it installs in debug builds.

Motivation

The 9.1 work gives both runtimes an identical, JS-observable error contract. Three inconsistencies remain, and each is a one-way door once apps depend on it:

• Crashes invisible to JS. A native exception on a random thread (not caused by JS) kills the app without ever touching the JS event layer on iOS. On Android, historically, such errors are routed into the JS error path — an asymmetry apps cannot write portable code against. Crash SDKs today must hook the native layer on each platform separately to see these.
• stackTrace is ambiguous. Both runtimes inject a combined stackTrace string property onto the error object before reporting. It predates the event model (it was the only context the __onUncaughtError hooks got), it duplicates error.stack, and it mutates a user-owned object — the pattern web specs deliberately avoid (that's why ErrorEvent carries message/filename/lineno instead of decorating the error). If we say nothing, it gets grandfathered into the unified contract, format and all.
• Runtimes own UI. Each runtime ships hundreds of lines of platform UI (the iOS UIKit error modal, the Android error activity) that render fatal errors in debug builds. With a cancelable error event, that responsibility can move to core/userland — where it can be themed, replaced, or removed — and the runtimes shrink to reporting only.

The foundation: WinterTC-aligned events (shipping in 9.1)

Both runtime PRs implement the same event substrate, byte-compatible in JS-observable behavior. This section is descriptive — it is what ios#409 and android#1985 already do — and is included so the proposals below can be evaluated against the full contract.

Standard surface (the part that overlaps WinterTC's Minimum Common Web Platform API — the interoperability target shared by Node, Deno, Bun, workerd and friends):

• Event and EventTarget as general-purpose global constructors — registration order, once/capture options, stopPropagation/stopImmediatePropagation, handleEvent objects, dispatchEvent returning !defaultPrevented. Usable for app/library eventing today, and the substrate for future primitives (AbortController/AbortSignal, fetch-shaped APIs) without new plumbing.
• globalThis as an event target (addEventListener/removeEventListener/dispatchEvent), in the same role as WorkerGlobalScope — no window required.
• ErrorEvent and PromiseRejectionEvent constructors; reportError() routing a caught-but-fatal error through the exact pipeline of an uncaught one.
• error and unhandledrejection are cancelable; preventDefault() = fully handled (no legacy hooks, no fatal log, no dev UI, no policy throw). rejectionhandled fires as a task, carrying the original reason. Unhandled rejections are tracked per isolate and reported once per event-loop turn; a handler attached before the turn ends cancels the report.
• Runtime dispatch is resilient: native code dispatches through closures captured at startup, so events keep firing even if app code overwrites globalThis.dispatchEvent. A throwing listener never stops the remaining listeners and never recursively dispatches.

NativeScript extensions (the part the web has no vocabulary for):

• uncaughtErrorPolicy: "report" | "throw" — one config key, same values, same default, on both platforms.
• interop.escapeException(x) — the portable per-call escape hatch converting a JS throw into a real native throw at the boundary, preserving original native-exception identity on rethrow.
• error.nativeException on errors surfaced from native throws, and JS stack traces carried on every native exception the machinery produces (documented userInfo keys + tns_javascriptStackTrace on iOS; synthesized real stack frames on Android).
• Legacy __onUncaughtError/__onDiscardedError hooks kept working (invoked only when no listener prevented) so @nativescript/core needs zero changes at 9.1.

The proposals below decide the three pieces of this contract that are still open.

Guide-level explanation

1. nativeuncaughterror

Status: landed on Android (17cd448); proposed here for iOS and for ratification as the shared spec.

A global event dispatched synchronously from the platform's last-chance handler (Android Thread.UncaughtExceptionHandler; iOS NSUncaughtExceptionHandler) for everything that reaches it un-marked — pure-native crashes, uncaught interop.escapeException forwards, bootstrap failures. The handler classifies nothing: un-reported-by-the-JS-pipeline is the entire rule.

globalThis.addEventListener("nativeuncaughterror", (e) => {
  crashReporter.recordFatal(e.error);                  // Error shell, message = native reason
  crashReporter.attachNative(e.error.nativeException); // the actual Throwable / NSException
  // e.preventDefault(); // optional: skip the dev error UI and the default
  //                     // (killing) handler — best-effort survival
});

Key semantics (as landed on Android):

• Payload matches the error event recipe. e.error is an Error whose message/name come from the native exception and whose nativeException is the wrapped original (Throwable on Android, NSException on iOS). One crash-SDK code path serves both events.
• Cancelable — preventDefault() skips the default behavior, best-effort. The default is the platform's fatal path: the debug error UI plus handing the exception to the default (process-killing) handler. Preventing is meaningful for background-thread crashes (the thread dies, the app lives); it cannot resurrect a crashed main thread, and the docs say so plainly. This is a different, weaker promise than error's preventDefault() — which is exactly why native deaths get their own event instead of overloading error.
• The containment invariant. error/unhandledrejection now fire only while the failure is fully containable (preventDefault() is honest); everything past that line is nativeuncaughterror. This also removes a footgun: a generic error listener can no longer accidentally spare a process whose crashed thread is already gone.
• One error, one report. Exceptions already reported by the JS pipeline (uncaughtErrorPolicy: "throw" rethrows carry a reported-to-JS mark) short-circuit the handler — no second event, no second hook. Uncaught escapes are un-marked by design (escapes bypass reporting), so crash SDKs get their last look at those here.
• Main-runtime fallback. Crashes on threads with no runtime of their own (plugin/executor threads) dispatch into the main runtime's isolate — previously those got no JS reporting at all.
• Best-effort delivery ("MAY fire"). No delivery for signals/aborts that bypass exception machinery (SIGSEGV, OOM kills, watchdog terminations). Additive to native crash SDKs, not a replacement.
• Legacy compatibility: the deprecated __onUncaughtError hook still fires for unprevented native crashes (that is what Application.uncaughtErrorEvent has received for years).

Open for iOS (see Unresolved questions): the reported-to-JS mark equivalent on NSException, thread marshaling from the crashing thread, and how much of "skip the default handler" is achievable — after NSUncaughtExceptionHandler returns, process death is generally unavoidable on iOS, so preventDefault() there may only suppress the runtime-added behavior (dev UI, hook chain), not termination. The unified contract wording accounts for this: "skips the platform's default behavior; survival is best-effort and platform/thread-dependent."

2. error.stackTrace becomes documented legacy

No rename, no removal — reclassification:

• Canonical, forever-spec sources: e.error.stack / e.reason.stack for the JS trace; e.error.nativeException (with callStackSymbols / getStackTrace()) for the native trace.
• stackTrace keeps working exactly as today (populated before event dispatch on both platforms) but is documented as a compatibility detail of the __onUncaughtError hook era — deprecated together with the hooks, removed no earlier than whenever the hooks are.
• Why: it duplicates .stack, it mutates a user-owned object (observable in JSON.stringify, collidable with library-owned properties), and keeping it out of the events contract frees both runtimes from freezing its exact composition format forever.
• If a runtime-composed trace (source-map-aware, origin + escape-site) proves valuable as first-class API, the correct home is a field on the event (an explicit NativeScript extension of ErrorEvent), where the platform owns the object it decorates. That is left as a follow-up, not part of 9.1.

3. Error UI moves to core/userland

Today: the iOS runtime renders a UIKit modal and the Android runtime an error activity for unhandled errors in debug builds — hardcoded look, hardcoded behavior, duplicated per platform.

Proposed end state: the runtimes never draw UI. Core installs a default listener in debug builds:

// @nativescript/core (debug builds), conceptually:
globalThis.addEventListener("error", (e) => {
  if (__DEV__) {
    showDevErrorOverlay(e.error);  // themable, replaceable, deletable
    e.preventDefault();            // core owns the outcome now
  }
});
globalThis.addEventListener("unhandledrejection", similar);

Userland (or a devtools package) can replace it wholesale. Release-build behavior is governed purely by uncaughtErrorPolicy and the app's own listeners.

Migration: in 9.1 the runtime UI remains (behind the existing flags, e.g. iOS showErrorDisplay) so nothing changes out of the box; core ships its listener-based overlay in a 9.x minor; NativeScript 10 deletes the runtime UI code paths and their flags.

Reference-level details

Event/dispatch matrix after this RFC (identical on both platforms):

Origin	Event	Cancelable	After preventDefault()	Unprevented terminal path
Uncaught JS exception	error	yes	fully handled	hooks → log → policy
Unhandled rejection	unhandledrejection	yes	fully handled	hooks → log (prefixed) → policy
Late handler attached	rejectionhandled	no	—	—
interop.escapeException	none at the throw (never reported); nativeuncaughterror if it reaches the last-chance handler uncaught	—	—	native throw, always
Native-layer death (pure-native crash, uncaught escape, bootstrap failure)	nativeuncaughterror	yes (best-effort)	skips dev error UI + default killing handler; survival platform/thread-dependent	legacy hook → platform default crash

• nativeuncaughterror ordering: fired synchronously from the last-chance handler before the platform's default handling proceeds, on a best-effort basis (the runtime must acquire the JS engine safely from the crashing thread — cross-thread via the main-runtime fallback when the thread has no runtime; if it cannot, the event is skipped — never deadlock a dying process).
• Marking: both runtimes carry a "reported to JS" mark on policy-thrown exceptions (Android isReportedToJs(); iOS needs the NSException equivalent); nativeuncaughterror fires only for exceptions without the mark. Escapes are deliberately un-marked.
• stackTrace docs move from the event-contract tables to the legacy-hooks section in both runtimes' documentation.

Drawbacks

• nativeuncaughterror runs JS on a crashing process — even read-only listeners can fail halfway. Mitigated by best-effort semantics and by documenting that listeners must be minimal and synchronous.
• Moving native crashes off the error event changes behavior for Android apps that relied on canceling them there; the containment ability survives via preventDefault() on nativeuncaughterror, but listeners must be updated (release-notes item, landed in android#1985).
• Moving the dev overlay to core adds one release where the experience depends on matching core + runtime versions.

Alternatives considered

• Overload error for native crashes everywhere (Android's status quo): rejected — makes cancelable a lie on iOS, and portable code can't distinguish "JS bug" from "native crash".
• Rename stackTrace (e.g. composedStackTrace): rejected — breaks shipped hook-era consumers (NativeScriptError.stackTrace is public core API) to fix an aesthetic problem; reclassification achieves the same spec hygiene for free.
• Keep runtime error UI, make it themeable: rejected — UI in two native codebases is the expensive place to iterate; the event layer already exists precisely so this can live in JS.

Adoption plan

Release	Step
9.1	Events + policy + escape land (ios#409, android#1985). stackTrace reclassified in docs. nativeuncaughterror: landed on Android; iOS implementation to match this spec. Native crashes stop firing error on Android (containment moves to nativeuncaughterror).
9.x	Core ships the listener-based dev overlay; runtime UI still available behind existing flags.
10	Runtime error UI removed; Android stops dispatching error for native crashes; __on* hooks and stackTrace injection enter final deprecation.

Unresolved questions

1. iOS implementation of nativeuncaughterror — NSUncaughtExceptionHandler runs on the crashing thread: acquiring the isolate can block against a wedged runtime thread (proposal: try-lock with a short timeout, skip on failure); an NSException reported-to-JS mark is needed (associated object, like the JS-stack attachment); and post-handler process death is unavoidable, so preventDefault() on iOS suppresses runtime-added behavior only. Needs prototyping.
2. Should reportError(interop.escapeException(x)) dispatch first or throw immediately? Today it dispatches (JS-side) before the native tail sees the brand — the one corner where "an explicit escape always wins" has an asterisk. Both platforms should pick one answer here.
3. Does core's dev overlay preventDefault() by default in debug? If yes, uncaughtErrorPolicy: "throw" is inert in debug builds — probably desirable, but worth stating explicitly.
4. Worker scope for nativeuncaughterror — Android answers this with current-thread-runtime, falling back to the main runtime for runtime-less threads. Should a crash on a worker's own thread fire on the worker global, the main global, or both? (JS-originated worker errors already have a defined chain; this is only about native deaths.)