Error Handling

Every action always finishes with a clear, predictable outcome — it never just rejects with a raw throw. Your handler can throw anything it likes (a declared NiceError, an undeclared one, or a plain Error); the runtime turns all of them into one typed result, so the place you call from always has the same shape to check against.

Two questions: expected and isUnhandled

When an action fails, there are two separate things you might want to know:

Question	Where to look	Meaning
Did this action say it could throw this?	result.expected (on the result)	You listed it with .throws(), so it’s a known, planned-for error.
Was this an unexpected crash?	error.isUnhandled (on the error)	Something threw that wasn’t a NiceError at all — a bug or infrastructure failure.

expected depends on which action you called: the very same NiceError can be expected for one action (which declared it) and unexpected for another (which didn’t). isUnhandled is a property of the error itself — it’s true only for the generic wrapper castNiceError puts around a non-NiceError throw, and it stays true even after the error travels over the network.

The recommended way — runToResult()

Get the outcome as a value and check it. No try/catch.

import { matchFirst } from "@nice-code/error";

const result = await act_user.action.getUser.request({ userId }).runToResult();

if (result.ok) {
  use(result.output);
} else if (result.expected) {
  // result.error is fully typed — it can only be one of this action's declared errors.
  matchFirst(result.error, {
    not_found: ({ userId }) => show404(userId),
    forbidden: () => showForbidden(),
  });
} else {
  // This action didn't declare this one. Check the error's own flag if you care which kind it is:
  if (result.error.isUnhandled) alertOncall(result.error); // an unexpected crash / bug / infra issue
  else report(result.error);                                // a real NiceError you just didn't .throws()
}

The outcome is one of three shapes:

type TActionResultOutcome<OUT, DECLARED> =
  | { ok: true; output: OUT }
  | { ok: false; expected: true; error: DECLARED }            // one of the errors this action declared
  | { ok: false; expected: false; error: NiceError };          // anything else

expected is always worked out fresh against the receiver’s own definition — it’s never trusted from the wire. So an error that arrived over the network is sorted exactly the same way as one thrown locally.

Throw style, with a typed check

If you prefer runToOutput() (which throws on failure), use the action’s isExpectedError check to narrow a caught error:

import { castNiceError, matchFirst } from "@nice-code/error";

try {
  const output = await act_user.action.getUser.request({ userId }).runToOutput();
} catch (e) {
  if (act_user.action.getUser.isExpectedError(e)) {
    // e is now narrowed to this action's declared errors
    matchFirst(e, { not_found: ({ userId }) => show404(userId), forbidden: () => showForbidden() });
  } else {
    report(castNiceError(e).toStructuredLog());
  }
}

When the connection itself fails

The two questions above sort failures that came back from a handler. A call can also fail because no transport ever came up — nothing reached a handler to succeed or throw. That surfaces as err_nice_transport with the id initialization_failed, and it carries the two things you need to act on it:

import { err_nice_transport, EWireConnectFailureKind } from "@nice-code/action";

if (err_nice_transport.isExact(e) && e.hasId("initialization_failed")) {
  const { endpoint, kind } = e.getContext("initialization_failed");

  if (kind === EWireConnectFailureKind.endpoint_answered_non_protocol) {
    // Something answered, but it isn't the backend — wrong URL, or a proxy/WAF in the way.
    reportMisroute(endpoint);
  } else if (kind === EWireConnectFailureKind.endpoint_unreachable) {
    showOfflineBanner();     // nothing there: server down, wrong port, firewall, offline
  }
}

kind is a typed discriminator — branch on it rather than matching the message, which is exactly the brittleness it exists to remove. endpoint names the URL that transport actually dialed, so the error is self-locating instead of “some transport, somewhere”.

If you’re holding a dial error from anywhere else in the stack, classifyConnectFailure(error) returns the same EWireConnectFailureKind for any error (unknown when it can’t tell). Both it and the enum are re-exported from @nice-code/action, so a consumer using actions never needs a direct @nice-code/wire import:

import { classifyConnectFailure, EWireConnectFailureKind } from "@nice-code/action";

if (classifyConnectFailure(e) === EWireConnectFailureKind.endpoint_unreachable) retryLater();

The full table of kind values, what each means, and the first thing to check for each is on Error Reference. The connection lifecycle these failures come out of is on The Connection.

Added in 0.87.0

Before 0.87 these failures flattened to a message string with no endpoint and no discriminator. kind, endpoint, and classifyConnectFailure all arrived together in that release.

Devtools

The browser devtools panel sorts each failed run by these same two questions. Based on result.expected, an error is labelled either Expected Error (declared) or Unexpected Error (undeclared / unhandled); and based on error.isUnhandled, an unexpected crash gets an extra unhandled badge. So the same distinction you check in code is the one you see in the timeline.