Error & 404 Handling

Relevant source files

The following files were used as context for generating this wiki page:

• cooltools/app/error.tsx
• cooltools/app/not-found.tsx
• cooltools/app/phones/[slug]/page.tsx
• cooltools/lib/phoneApi.ts
• cooltools/app/phones/page.tsx
• cooltools/middleware.ts

The Error and 404 handling system in the CoolTools platform is designed to provide a resilient user experience by capturing runtime exceptions and resource navigation failures. The architecture leverages Next.js file-based conventions to provide global fallback UIs, while individual page components implement specific state-driven error handling for data fetching operations.

This system ensures that users are notified of issues such as missing mobile devices, API timeouts, or unexpected application crashes, and provides clear paths to recover via navigation links or retry mechanisms.

Global Application Error Boundaries

The application utilizes a global error boundary to catch uncaught exceptions in the client-side component tree. This is implemented as a client component that receives the error object and a reset function.

Component Logic

When an error occurs, the system logs the error to the console and displays a stylized error card. The reset function allows users to attempt to re-render the segment that failed, which is useful for intermittent network issues.

404 Not Found Handling

The project implements a custom NotFound component to handle instances where a user navigates to a non-existent route or a resource that does not exist.

Navigation Recovery

The 404 page provides two primary recovery paths:

1. Home Navigation: Returns the user to the landing page.
2. Browse Phones: Redirects the user to the phone listing page to find valid content.

Component	UI Elements	Purpose
NotFound	"404", "Page Not Found"	Displays error code and description
Link (Home)	"Go Home" button	Navigation recovery to index
Link (Search)	"Browse Phones" button	Navigation recovery to phones list

Sources: cooltools/app/not-found.tsx:1-34

Data Fetching and API Resilience

The core of the application's error handling logic resides in the data layer and individual page components, specifically when interacting with the external api-mobilespecs service.

API Retry Logic

The getPhoneDetails function implements a retry mechanism to handle transient network failures. It attempts to fetch data multiple times with an incremental delay before returning a null value.

Page-Level Error States

Components like the Phone Details page manage internal loading and error states. If the API returns no data or throws an exception, the UI switches from a loading spinner to an error message with a "Back to Phones" navigation option.

if (error || !phone) {
  return (
    <div className="text-center">
      <h2 className="text-2xl font-bold text-red-600">
        {error || 'Phone not found'}
      </h2>
      <Link href="/phones">Back to Phones</Link>
    </div>
  );
}

Sources: cooltools/app/phones/[slug]/page.tsx:75-91, cooltools/app/phones/page.tsx:103-114

Security and Middleware Interception

The application includes middleware that sets security headers on responses, preventing certain classes of attacks that could lead to unexpected error states or security vulnerabilities.

Security Headers

• X-Content-Type-Options: nosniff: Prevents the browser from interpreting files as a different MIME type.
• X-Frame-Options: DENY: Prevents clickjacking.
• X-XSS-Protection: 1; mode=block: Enables browser XSS filtering.

Sources: cooltools/middleware.ts:6-15

Summary of Error Components

File	Type	Strategy
app/error.tsx	Global Boundary	Catch-all for React runtime errors with reset() capability.
app/not-found.tsx	Route Fallback	Static 404 page with navigation recovery links.
lib/phoneApi.ts	Data Layer	Retry logic (3 attempts) and request deduplication.
app/phones/[slug]/page.tsx	Component State	Localized error messaging for missing specific device slugs.
app/phones/page.tsx	Component State	UI feedback for global list fetch failures.

Sources: cooltools/app/error.tsx, cooltools/app/not-found.tsx, cooltools/lib/phoneApi.ts, cooltools/app/phones/[slug]/page.tsx, cooltools/app/phones/page.tsx