Implement and test a Next.js route error boundary that reports an unexpected failure safely and gives the user clear recovery choices.

Create an App Router error.tsx boundary for one route segment. It must announce a concise failure message, report only a safe route and optional digest, call reset() when the user retries, and retain a link out of the failed segment. Do not expose the raw exception, retry automatically, or use the boundary for expected validation and API outcomes.

When an unexpected render failure reaches the boundary, the user sees We could not load this page, a Try again button, and a Back to drills link. One safe report contains /tracks/dotnet-full-stack and digest abc123, but not Database password leaked. Selecting Try again invokes reset() exactly once; a second failure remains recoverable instead of entering an automatic retry loop.

• error.tsx must be a Client Component.
• Report a digest or generated reference plus a non-sensitive route; never render or transmit arbitrary exception text from this UI.
• Reporting failure must not hide the recovery controls.
• Retry is user initiated and calls the supplied reset() function once.
• Keep navigation outside the failed operation available.
• Model expected errors such as invalid input or a normal 404 in their explicit UI paths.

1. Put error.tsx at the narrowest route segment that can recover independently.
2. Mark it with "use client" because the boundary receives error and reset and uses an effect.
3. Report a sanitized payload from useEffect; make the reporter tolerant of duplicate delivery and swallow telemetry failure locally.
4. Render a stable message with an accessible heading or alert, a retry command, and a link outside the failed segment.
5. Test that unsafe error text is absent, the safe reference is optional, retry invokes reset, navigation remains, and reporting failure does not break the fallback.
6. Keep expected API and form errors in normal state rather than throwing them into this boundary.

// app/tracks/[trackSlug]/error.tsx
"use client";

import Link from "next/link";
import { useEffect } from "react";
import { reportFrontendError } from "@/lib/telemetry";

export default function TrackError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    void reportFrontendError({
      digest: error.digest ?? null,
      route: window.location.pathname,
    }).catch(() => undefined);
  }, [error]);

  return (
    <section role="alert" aria-labelledby="track-error-title">
      <h1 id="track-error-title">We could not load this page</h1>
      <p>Try this page again, or return to the drill catalog.</p>
      {error.digest ? <p>Reference: {error.digest}</p> : null}
      <button type="button" onClick={reset}>Try again</button>
      <Link href="/drills">Back to drills</Link>
    </section>
  );
}

it("reports safely and lets the user retry", async () => {
  const user = userEvent.setup();
  const reset = vi.fn();
  reportFrontendError.mockResolvedValue(undefined);
  render(
    <TrackError
      error={Object.assign(new Error("Database password leaked"), { digest: "abc123" })}
      reset={reset}
    />,
  );

  expect(screen.getByRole("alert")).toBeVisible();
  expect(screen.queryByText(/Database password leaked/i)).not.toBeInTheDocument();
  expect(screen.getByText(/Reference: abc123/i)).toBeVisible();
  expect(screen.getByRole("link", { name: "Back to drills" })).toHaveAttribute("href", "/drills");
  await waitFor(() => expect(reportFrontendError).toHaveBeenCalledWith({
    digest: "abc123",
    route: expect.any(String),
  }));

  await user.click(screen.getByRole("button", { name: "Try again" }));
  expect(reset).toHaveBeenCalledTimes(1);
});

A segment boundary limits the blast radius and preserves parent layouts, but it cannot recover failures in its own layout or in event handlers that never reach the render boundary. A broad global boundary catches more, yet provides less contextual recovery. Telemetry should deduplicate by a stable event identity because effects and retries may report more than once; losing one telemetry call is preferable to replacing the recovery UI with another error.

• No digest is available, so the UI omits the reference cleanly.
• reset() rerenders the segment but the underlying dependency still fails.
• The telemetry endpoint rejects or is blocked by the browser.
• The exception happens in an event handler and needs explicit local handling.
• The boundary itself throws because it imports fragile application code.
• A parent layout fails and bypasses this narrower boundary.

• The fallback renders without relying on the failed route data.
• Raw message, stack, request data, and secrets never appear in the DOM or report payload.
• Digest presence and absence both render valid UI.
• Retry invokes reset() once and never loops automatically.
• The escape link remains keyboard reachable.
• Rejected telemetry promises do not create an unhandled rejection.
• Expected errors are covered by their normal state tests rather than this boundary test.

• The file is missing "use client", so it cannot use the boundary contract correctly.
• The UI prints error.message or a stack trace and leaks implementation details.
• Retry runs automatically and creates a failure loop.
• Reporting throws from the boundary and replaces one failure with another.
• The boundary is global even though only one route segment needs recovery.
• Normal validation, authorization, or not-found states are thrown instead of modeled explicitly.