onError()

Subscribe to failures of the Dashlet handle. This is the error channel: failures that the library can observe but not resolve — timeouts, host errors, and errors thrown by your own listeners.

1. Signature

onError(listener: (error: unknown) => void): () => void;

  • listener — receives the error value (unknown: a TimeoutError, a host error payload, or an exception thrown by a listener).

  • Returns an unsubscribe function.

2. What routes here

The library’s documented routing (exact, as implemented):

  • Listener errors. An exception thrown by an onInit or onUpdate listener — including a replayed onInit delivery to a late subscriber — is caught and delivered to every onError listener. This is the primary source of errors on a well-behaved dashlet page: a bug in your render function surfaces here, not in an uncaught exception.

  • Replaced host global (rich client only). When other code on the page replaces window.osDashletInit, the rich client’s selection-change callbacks go to that code instead of the dashlet. Once the dashlet has settled in the rich client, every onError listener receives one plain Error whose message starts with Dashlet: window.osDashletInit was replaced by other code. It arrives at most once per dashlet instance, also for a replacement made before the init settled. The library does not take the global back and does not forward host calls to the foreign function: remove the second dashlet layer from the page. No report is made in the webclient, in standalone, or for a rich client that settled through the webclient wire, and a second installDashletGlobal call is not a replacement. After the init settled only assignments are observed: a later global function declaration, Object.defineProperty, delete or a second copy of the library goes unreported.

  • No cascade. If an onError listener itself throws, that exception is swallowed — an error listener must not cascade. (This keeps a broken error handler from taking down the host call or the other listeners.)

The subscription’s documented purpose is to observe failures in general (timeouts, host errors, listener errors, the replaced host global); which specific error values appear depends on the failure path (see Errors and call for the method-call error paths).

3. Notes

  • onError does not change control flow: it is observation, not recovery. Failing method calls still reject their own promises; onError gives a second, side-band view.

  • Register it early (top level, next to installDashletGlobal) so that listener errors from the first settle are not missed.

4. Examples

const off = dashlet.onError((error) => {
    console.error('dashlet failure:', error);
    // e.g. log, toast, degrade — no rethrow
});

// later
off(); // unsubscribe