Route exception handling#

When a guard, a matcher or a resolver raises a declared exception, this page is where you say what happens next: redirect, render a dedicated component, stay put, or carry on. One map per route resolves the union of every code those three steps can produce — and the compiler checks that the map is exactly complete, no more and no less.

Use it when a route's guards, matchers or resolvers can fail in ways the user should see. Not when the failure is local to one primitive — read it off exceptions() instead, see Exceptions as values.

The common case#

USER_DISABLED: craftExceptionHandler(function* ({ renderComponent }) {
  return renderComponent({
    loadComponent: () =>
      import('./user-disabled-error-page').then(
        (m) => m.UserDisabledErrorPage,
      ),
    componentDeps:
      {} as import('./user-disabled-error-page').GenDeps_UserDisabledErrorPage,
  });
}),

NOT_AUTHENTICATED: craftExceptionHandler(function* ({ redirectTo }) {
  return yield* redirectTo({
    to: 'auth/login',
    queryParams: { reason: 'session-expired' },
  });
}),

canActivate / canMatch / resolve stay your writing API — each may raise a typed craftException. Instead of an inline resolver map per guard, a single handleExceptions map on the route resolves the union of every code reachable from those three steps. The non-blocking CraftRouterOutlet applies the chosen outcome after the URL has committed, so a slow guard never freezes navigation.

The route result also exposes a route-scoped signal helper per code, such as injectDemoUserIdUserDisabledException(). It returns the exact exception and payload for the locally rendered branch, and is cleared on the next navigation.

A full route, end to end#

const { profileQuery } = query('profileQuery', {
  params: () => true,
  loader: function* () {
    return yield* CraftHttpClient.get(({ response }) => ({
      url: '/api/profile',
      success: response<Profile>(),
      exceptions: [
        function* ({ status, code }) {
          if (!(yield* status(403))) return;
          if (!(yield* code('USER_DISABLED'))) return;
          return craftException({ _tag: 'USER_DISABLED' });
        },
      ],
    }));
  },
});

craftRoute(
  'user/:userId',
  {
    loadComponent: ({ withRetry }) => withRetry(import('./user-detail')),
    componentDeps: {} as import('./user-detail').GenDeps_UserDetail,
    canMatch: function* () {
      const ff = yield* FeatureFlags();
      return ff.userPageEnabled ? true : craftException({ _tag: 'FEATURE_OFF' });
    },
    canActivate: function* () {
      const user = yield* Auth();
      return user.value() ?? craftException({ _tag: 'NOT_AUTHENTICATED' });
    },
    resolve: craftResolve(function* () {
      return yield* craftUntilSettled(profileQuery);
    }),
  },
  {
    FEATURE_OFF: craftExceptionHandler(function* ({ redirectTo }) {
      return yield* redirectTo({ to: 'home' });
    }),
    NOT_AUTHENTICATED: craftExceptionHandler(function* ({ redirectTo, phase }) {
      return yield* redirectTo({
        to: 'login',
        queryParams: phase === 'active' ? { reason: 'session-expired' } : {},
      });
    }),
    USER_DISABLED: craftExceptionHandler(function* ({ globalError }) {
      return globalError();
    }),
    HttpError: craftExceptionHandler(function* ({ globalError }) {
      return globalError();
    }),
  },
),

canActivate / canMatch are bare generator functions — there is no guard wrapper and no inline resolvers argument. Every reachable code flows to the third craftRoute(...) argument.

Handler context#

Every handler receives a CraftExceptionHandlerContext typed for its exception code:

A handler is always a synchronous generator wrapped with craftExceptionHandler. It may resolve services but cannot suspend with craftUntilSettled / craftUntilDefined.

Outcomes#

Each handler receives a context and returns an outcome constructor:

The context also carries the typed exception, its payload, the native redirect helpers (createUrlTree / navigate / navigateByUrl), and the navigation phase (see below). A handler may be a generator that yield*s craft services before its outcome.

Examples#

Typed payload and UrlTree#

Use redirectTo(...) for registered application routes and redirectUrl(...) for a prebuilt UrlTree:

{
  NOT_AUTHENTICATED: craftExceptionHandler(function* ({ redirectTo }) {
    return yield* redirectTo({ to: 'auth/login' });
  }),
  RATE_LIMITED: craftExceptionHandler(function* ({ payload, redirectTo }) {
    return yield* redirectTo({
      to: 'cooldown',
      queryParams: { retryAfter: String(payload.retryAfter) },
    });
  }),
}

Here payload is inferred from craftException({ _tag: 'RATE_LIMITED' }, { retryAfter: 30 }).

Initial entry versus live guard#

{
  NOT_AUTHENTICATED: craftExceptionHandler(function* ({ phase, redirectTo }) {
    return yield* redirectTo({
      to: 'login',
      queryParams: phase === 'active' ? { reason: 'session-expired' } : {},
    });
  }),
}

Local, global, stay, and noop outcomes#

{
  ACCOUNT_LOCKED: craftExceptionHandler(function* ({ renderComponent }) {
    return renderComponent({
      component: AccountLockedPage,
      componentDeps: {} as import('./account-locked-page').GenDeps_AccountLockedPage,
    });
  }),
  MAINTENANCE: craftExceptionHandler(function* ({ renderComponent }) {
    return renderComponent({
      loadComponent: () => import('./maintenance-page').then((m) => m.MaintenancePage),
      componentDeps: {} as import('./maintenance-page').GenDeps_MaintenancePage,
    });
  }),
  HttpError: craftExceptionHandler(function* ({ globalError }) { return globalError(); }),
  UNSAVED_CHANGES: craftExceptionHandler(function* ({ stay }) { return stay(); }),
  OPTIONAL_PROFILE_UNAVAILABLE: craftExceptionHandler(function* ({ noop }) { return noop(); }),
}

The descriptor is checked independently with the O(1) RouteExceptionComponentCheckedDI; it is not part of the routed component's RouteCheckedDI proof. Architecture tests fail if that proof is missing or not armed with CanRun.

Handler using a craft service#

{
  FORBIDDEN_ROLE: craftExceptionHandler(function* ({ redirectUrl }) {
    const config = yield* RedirectConfig();
    return redirectUrl(config.unauthorizedUrl);
  }),
}

Dependencies yielded by handlers participate in route DI checking, like dependencies yielded by guards and resolvers.

Exhaustiveness#

The union is only resolvable once the whole collection is inferred, so exhaustiveness is asserted after craftRoutes rather than inline on each route:

export const { demoRoutes } = craftRoutes('demo', [
  /* … */
]);

// Compile error if any route's handleExceptions misses — or over-covers — a reachable code.
assertExhaustiveRouteExceptions(demoRoutes);

Architecture tests fail if a craftRoutes(...) collection has no assertExhaustiveRouteExceptions.

A missing code (e.g. resolve can throw USER_DISABLED but no handler) and an extra code (a handler for a code nothing can produce) are both type errors, naming the offending route + codes.

Pitfalls#

HttpError appears or disappears depending on the craftUntilSettled form. This is the most common surprise:

• craftUntilSettled(CraftHttpClient.get(...)) excludes HttpError from the routable union and rethrows it. The outlet sends that navigation error to the global error component.

• craftUntilSettled(queryRef) routes every exception the query exposes. When its loader returns a CraftHttpClient request, that includes HttpError, so the route must declare an explicit handler such as HttpError: craftExceptionHandler(function* ({ globalError }) { return globalError(); }).

Declared business exceptions remain routable in both forms.

A handler cannot suspend. It may yield* services, but not craftUntilSettled / craftUntilDefined.

Over-covering is an error too. A handler for a code nothing can produce fails the exhaustiveness assert, same as a missing one.

See Also#

• Exceptions as values — the concept

• Route guards — where exceptions are raised

• Global error component

• Architecture rules — assertRouteDiProofs keeps the exhaustiveness assert in place