What happens to a failure at each point in the pipeline, and which error class a caller sees.
| Failure | Behavior |
|---|---|
| Authorization | authorize returning false creates IpcAuthorizationError. A thrown/rejected authorization error is preserved. Handlers reject; listeners use listener-failure behavior below. |
| Validation | A callback validator's thrown/rejected value is preserved; a schema reporting issues creates IpcValidationError carrying them. The channel callback is not called. Handlers reject; listeners use listener-failure behavior below. |
| Handler callback | A thrown value or rejected promise is preserved and returned through Electron's invoke rejection path. |
| Stream callback | authorize and validate failures reject the start invoke, so the renderer's first next() rejects with them. A throw before the first yield or mid-stream, a callback that returns no iterable, or a chunk that cannot be sent is reported as (id, "error", String(error)) after the chunks already sent; the renderer's next() rejects with Error invoking remote method '<channel>': <error>, the same shape as a failed invoke, and main calls the iterator's return(). A renderer cancel or a destroyed sender sends nothing further, aborts the call's event.signal, and calls return(); if that throws, the error is logged, since nobody is listening. onListenerError is not involved. |
| Listener callback | Synchronous throws and promise rejections are caught. onListenerError(error, context, event) is called once, or the error is logged when no hook exists. If the hook itself throws, that secondary error is logged; it is never rethrown into Electron's event emitter. |
| Cleanup | Every relevant channel cleanup and module cleanup is attempted. State is removed even on failure. One or more failures reject with AggregateError; rollback errors are aggregated with the original failure, original error first. |
| Registration collision | Electron registration errors are preserved and already-attached channels are rolled back. Container-detected duplicate physical channels reject with IpcChannelCollisionError; cleanup failure produces an AggregateError containing both errors. |
| Generator diagnostics | TypeScript configuration and option errors, and unsafe-to-generate conditions, throw Error and abort without writing output. Syntax and type errors abort only when they are in an IPC source or a file one imports — see What gets type-checked in the README. Analyzer limitations such as spreads and duplicate event declarations are returned in each module's warnings and logged, but generation continues. CLI commands report thrown diagnostics and exit non-zero; check also exits non-zero when generated output is stale. |
load emits error only when an error listener is attached, so Node's special unhandled error event cannot mask the rejection. loaded is emitted after commit and unloaded after state removal.
Observers are notifications, not participants. An exception thrown by a loaded, unloaded, or error listener never changes the outcome of the lifecycle operation that emitted it:
has(), names, and the registered channels. A throwing loaded listener cannot leave a rejected loadAll() partially committed, and cannot un-commit a successful load().error listener cannot mask the registration or cleanup failure it was told about, and a throwing unloaded listener cannot swallow an AggregateError from a failed cleanup.error, wrapped in IpcObserverError so it is distinguishable from a lifecycle failure. It carries event, moduleName, and the original reason.One case is terminal and silent by design: an error listener that throws while being told about another observer's exception. Re-entering error would recurse and there is no other channel, so it is dropped. Keep error listeners defensive.