Skip to content

Communicate with middleware via errors

Astro>=5.0.0

In an on-demand rendered Astro page, you can return a Response directly from the page’s frontmatter—for example, return Astro.redirect("/login").

That works well for one-off checks, but gets repetitive once you extract shared logic like page-level authentication or role checks into helper functions. Because a helper function cannot return on behalf of the page, every page ends up repeating the same guard boilerplate:

---
const auth = requireAuth(Astro);
if (auth instanceof Response) return auth;
const { user } = auth;
---

Because Astro executes a page’s frontmatter (and API endpoint handlers) inside your middleware’s await next() call, you can invert this pattern: throw a signal from your helper and catch it in middleware to return the Response.

This gives you two benefits:

  • Cleaner page code and TypeScript narrowing: Helpers throw when access is denied and return a narrowed, guaranteed-valid value otherwise.
  • Centralized error handling: Middleware can turn intentional control-flow signals into responses while letting unexpected errors flow to your logger and 500.astro error page.

Below are two ways to implement this pattern yourself, plus a ready-made integration (@inox-tools/cut-short) if you would rather skip writing the middleware boilerplate.

Section titled “Option 1: Custom error class (recommended)”

Wrapping the response builder in a custom Error subclass is the most idiomatic approach. It preserves stack traces, avoids mutating Web Standard Response objects, and works cleanly with linters and error-tracking tools.

First, define an ErrorWithResponse class whose render() method produces the Response (synchronously or asynchronously):

src/lib/errors.ts
export class ErrorWithResponse extends Error {
readonly #builder: () => Response | Promise<Response>;
constructor(message: string, builder: () => Response | Promise<Response>) {
super(message);
this.name = "ErrorWithResponse";
this.#builder = builder;
}
render() {
return this.#builder();
}
}

Next, catch ErrorWithResponse instances in your middleware and return the response they build, rethrowing everything else:

src/middleware.ts
import { defineMiddleware } from "astro:middleware";
import { ErrorWithResponse } from "./lib/errors";
export const onRequest = defineMiddleware(async (_context, next) => {
try {
return await next();
} catch (error) {
if (error instanceof ErrorWithResponse) {
return await error.render();
}
// Report or log unexpected errors here before rethrowing
throw error;
}
});

Now your authorization helper can throw an ErrorWithResponse whenever a check fails, and narrow the return type when it succeeds:

src/lib/auth.ts
import type { APIContext } from "astro";
import { ErrorWithResponse } from "./errors";
export type AuthUser =
| { id: string; role: "free" }
| { id: string; role: "premium" }
| { id: string; role: "admin" };
type RouteContext = Pick<APIContext, "locals" | "url" | "redirect">;
export function requireRole<T extends AuthUser["role"] = "premium">(
{ locals, url, redirect }: RouteContext,
roles: T[] = ["premium"] as T[],
) {
const user = locals.user;
if (!user || !roles.includes(user.role as T)) {
const loginUrl = `/login?redirect=${encodeURIComponent(url.pathname + url.search)}`;
throw new ErrorWithResponse("Unauthorized", () => redirect(loginUrl, 302));
}
return {
user: user as Extract<AuthUser, { role: T }>,
};
}

In any server-rendered page, call the helper directly in the frontmatter without any instanceof Response checks:

src/pages/premium.astro
---
import { requireRole } from "../lib/auth";
// Redirects unauthorized visitors via middleware.
// `user` is narrowed to `{ id: string; role: "premium" }`.
const { user } = requireRole(Astro);
---
<h1>Welcome, premium member {user.id}</h1>

The same helper also works inside API endpoints, or with custom status codes like new Response("Forbidden", { status: 403 }) or Response.json(...).

If you prefer not to introduce a custom error class, you can throw a Response directly—such as the one returned by Astro.redirect()—and attach a marker so your middleware only intercepts responses you threw intentionally.

Using a Symbol avoids accidental property collisions:

src/lib/auth.ts
import type { APIContext } from "astro";
export const INTERNAL_RESPONSE = Symbol("internalResponse");
type RouteContext = Pick<APIContext, "locals" | "url" | "redirect">;
export function requireAuth({ locals, url, redirect }: RouteContext) {
if (!locals.user) {
const loginUrl = `/login?redirect=${encodeURIComponent(url.pathname + url.search)}`;
throw Object.assign(redirect(loginUrl, 302), {
[INTERNAL_RESPONSE]: true,
});
}
return { user: locals.user };
}

Then check for both instanceof Response and the marker in your middleware:

src/middleware.ts
import { defineMiddleware } from "astro:middleware";
import { INTERNAL_RESPONSE } from "./lib/auth";
export const onRequest = defineMiddleware(async (_context, next) => {
try {
return await next();
} catch (error) {
if (error instanceof Response && INTERNAL_RESPONSE in error) {
return error;
}
// Report or log unexpected errors here before rethrowing
throw error;
}
});

Skip the boilerplate with @inox-tools/cut-short

Section titled “Skip the boilerplate with @inox-tools/cut-short”

If you don’t want to maintain your own error class and middleware, @inox-tools/cut-short wraps this exact pattern into an Astro integration. Under the hood, it injects a middleware that catches an internal CarrierError thrown by its endRequest() helper.

Add the integration to your project:

npx astro add @inox-tools/cut-short

Then call endRequest() from any page frontmatter, API endpoint, middleware, or helper called by them—with either a Response or a sync/async builder function:

src/lib/auth.ts
import { endRequest } from "@it-astro:cut-short";
import type { APIContext } from "astro";
type RouteContext = Pick<APIContext, "locals" | "url" | "redirect">;
export function requireAuth({ locals, url, redirect }: RouteContext) {
if (!locals.user) {
const loginUrl = `/login?redirect=${encodeURIComponent(url.pathname + url.search)}`;
endRequest(redirect(loginUrl, 302));
}
// `endRequest` returns `never`, so `locals.user` is automatically narrowed.
return { user: locals.user };
}

Beyond eliminating the custom middleware, @inox-tools/cut-short also provides:

  • disableStreaming: true: An optional integration setting that disables HTML streaming so even child components inside a page can call endRequest().
  • cancelPrerender(): Skips emitting a static file for a prerendered route during builds.
  • Only works in page frontmatter and API endpoints, not child components: Astro streams HTML responses by default. Once a page’s frontmatter finishes executing, await next() resolves and the response begins streaming. If a child .astro component throws during template rendering, the middleware’s try / catch block has already finished and will not catch it. Always run checks that throw in the top-level page frontmatter or endpoint handler (unless you explicitly disable HTML streaming, e.g. via @inox-tools/cut-short’s disableStreaming option).
  • Requires on-demand rendering: Prerendered static pages are generated at build time rather than per request. Make sure routes using this pattern are server-rendered (output: "server" or export const prerender = false).
  • Always rethrow unknown errors: Only intercept errors you explicitly recognize so unexpected bugs are still logged and handled by Astro’s error page.
  • Ordering with sequence(): When composing multiple middleware with sequence(), place your error-catching middleware ahead of any middleware whose errors you also want it to intercept (and ensure intermediate middleware do not swallow thrown errors).