How can you implement custom error handling in Next.js

How can you implement custom error handling in Next.js

Error handling is an essential part of any robust web application. It ensures that users have a seamless experience even when something goes wrong. Next.js, a popular React framework, provides several built-in mechanisms for error handling, but it also allows developers to customize these mechanisms to fit the specific needs of their applications. In this article, we will explore how to implement custom error handling in Next.js, covering both server-side and client-side strategies.

Understanding Error Handling in Next.js

Next.js comes with built-in error handling mechanisms that help manage unexpected errors gracefully. By default, Next.js provides a custom error page that is displayed whenever an unhandled error occurs during server-side rendering or client-side navigation. The default error page is minimal and functional, but for a polished user experience, you often need to customize it.

Built-in Error Pages

Next.js includes two default error pages:

  • 404 Page: Displayed when a user navigates to a non-existent route.
  • 500 Page: Displayed when an unhandled error occurs during server-side rendering.

These pages can be customized by creating specific files in your Next.js project.

Customizing the 404 Page

To create a custom 404 page, you need to add a 404.js file to the pages directory. This page will be rendered whenever a 404 error occurs.

// pages/404.js
import React from 'react';

const Custom404 = () => {
  return (
    <div>
      <h1>404 - Page Not Found</h1>
      <p>Sorry, the page you are looking for does not exist.</p>
    </div>
  );
};

export default Custom404;

With this custom 404 page, you can provide a more user-friendly message and layout, including navigation options back to the homepage or other important areas of your site.

Customizing the 500 Page

To customize the 500 error page, create a 500.js file in the pages directory. This page will be displayed for server-side errors that are not handled by the application.

// pages/500.js
import React from 'react';

const Custom500 = () => {
  return (
    <div>
      <h1>500 - Server-side Error</h1>
      <p>Something went wrong on our end. Please try again later.</p>
    </div>
  );
};

export default Custom500;

This custom 500 page allows you to provide a better experience when server-side errors occur, reassuring users and offering potential actions they can take.

Error Boundaries for Client-side Errors

Error boundaries are a React feature that lets you catch JavaScript errors anywhere in the component tree, log those errors, and display a fallback UI instead of the component tree that crashed. Next.js supports error boundaries, allowing you to handle client-side errors gracefully.

Creating an Error Boundary

To create an error boundary, you need to define a component that implements the componentDidCatch lifecycle method or the getDerivedStateFromError static method.

// components/ErrorBoundary.js
import React, { Component } from 'react';

class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    console.error("Error caught by ErrorBoundary:", error, errorInfo);
    // You can also log the error to an error reporting service here
  }

  render() {
    if (this.state.hasError) {
      return (
        <div>
          <h1>Something went wrong.</h1>
          <p>We apologize for the inconvenience. Please try again later.</p>
        </div>
      );
    }

    return this.props.children; 
  }
}

export default ErrorBoundary;

Using the Error Boundary

Wrap your application or specific parts of your application with the ErrorBoundary component to catch errors in the subtree.

// pages/_app.js
import React from 'react';
import App from 'next/app';
import ErrorBoundary from '../components/ErrorBoundary';

class MyApp extends App {
  render() {
    const { Component, pageProps } = this.props;
    return (
      <ErrorBoundary>
        <Component {...pageProps} />
      </ErrorBoundary>
    );
  }
}

export default MyApp;

With this setup, any errors that occur in the component tree wrapped by ErrorBoundary will be caught, and the fallback UI will be displayed.

Custom Error Handling in API Routes

Next.js API routes allow you to create serverless functions that can handle requests. Proper error handling in these routes ensures that clients receive meaningful error messages and status codes.

Basic Error Handling in API Routes

To handle errors in API routes, you can use try-catch blocks and send appropriate HTTP status codes and messages.

// pages/api/example.js
export default function handler(req, res) {
  try {
    // Your logic here
    if (someCondition) {
      throw new Error('Something went wrong');
    }
    res.status(200).json({ message: 'Success' });
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
}

Creating a Centralized Error Handler

For more complex applications, it’s useful to create a centralized error handling mechanism. This can involve defining custom error classes and middleware-like functions to handle errors uniformly.

// lib/errors.js
class CustomError extends Error {
  constructor(statusCode, message) {
    super(message);
    this.statusCode = statusCode;
  }
}

const handleError = (err, res) => {
  const { statusCode, message } = err;
  res.status(statusCode || 500).json({
    status: "error",
    statusCode,
    message
  });
};

module.exports = {
  CustomError,
  handleError
};

// pages/api/example.js
import { CustomError, handleError } from '../../lib/errors';

export default function handler(req, res) {
  try {
    // Your logic here
    if (someCondition) {
      throw new CustomError(400, 'Bad Request');
    }
    res.status(200).json({ message: 'Success' });
  } catch (error) {
    console.error(error);
    handleError(error, res);
  }
}

With this approach, you can define various custom error classes and ensure that all errors are handled consistently across your API routes.

Logging Errors

Logging is crucial for monitoring and debugging your application. Next.js does not come with a built-in logging solution, but you can integrate popular logging libraries like winston or external services like Sentry for comprehensive error tracking.

Using Winston for Logging

  1. Install Winston:
npm install winston
  1. Configure Winston in a separate file:
// lib/logger.js
import { createLogger, format, transports } from 'winston';

const logger = createLogger({
  level: 'info',
  format: format.combine(
    format.timestamp(),
    format.printf(({ timestamp, level, message }) => {
      return `${timestamp} [${level}]: ${message}`;
    })
  ),
  transports: [
    new transports.Console(),
    new transports.File({ filename: 'error.log', level: 'error' }),
    new transports.File({ filename: 'combined.log' }),
  ],
});

export default logger;
  1. Use the logger in your application:
// pages/api/example.js
import logger from '../../lib/logger';

export default function handler(req, res) {
  try {
    // Your logic here
    if (someCondition) {
      throw new Error('Something went wrong');
    }
    res.status(200).json({ message: 'Success' });
  } catch (error) {
    logger.error(error.message);
    res.status(500).json({ error: 'Internal Server Error' });
  }
}

Using Sentry for Error Tracking

  1. Install Sentry:
npm install @sentry/nextjs
  1. Configure Sentry in your Next.js project:
// sentry.server.config.js
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: 'YOUR_SENTRY_DSN',
  tracesSampleRate: 1.0,
});

// sentry.client.config.js
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: 'YOUR_SENTRY_DSN',
  tracesSampleRate: 1.0,
});
  1. Wrap your _app.js with Sentry’s error boundary:
// pages/_app.js
import React from 'react';
import * as Sentry from '@sentry/nextjs';
import App from 'next/app';

class MyApp extends App {
  render() {
    const { Component, pageProps } = this.props;
    return <Component {...pageProps} />;
  }
}

export default Sentry.withErrorBoundary(MyApp, {
  fallback: <p>An error has occurred</p>,
});
  1. Use Sentry in your API routes:
// pages/api/example.js
import * as Sentry from '@sentry/nextjs';

export default async function handler(req, res) {
  try {
    // Your logic here
    if (someCondition) {
      throw new Error('Something went wrong');
    }
    res.status(200).json({ message: 'Success' });
  } catch (error) {
    Sentry.captureException(error);


    res.status(500).json({ error: 'Internal Server Error' });
  }
}

Handling Errors in getServerSideProps and getStaticProps

Next.js provides getServerSideProps and getStaticProps for data fetching in pages. Proper error handling in these functions ensures that your application can handle data fetching errors gracefully.

Error Handling in getServerSideProps

Use try-catch blocks to handle errors in getServerSideProps.

// pages/server-side.js
export async function getServerSideProps(context) {
  try {
    const res = await fetch('https://api.example.com/data');
    const data = await res.json();

    if (!res.ok) {
      throw new Error(data.message || 'Failed to fetch data');
    }

    return {
      props: { data },
    };
  } catch (error) {
    console.error(error);
    return {
      props: { error: 'Failed to load data' },
    };
  }
}

const ServerSidePage = ({ data, error }) => {
  if (error) {
    return <div>{error}</div>;
  }

  return <div>{JSON.stringify(data)}</div>;
};

export default ServerSidePage;

Error Handling in getStaticProps

Similarly, handle errors in getStaticProps using try-catch blocks.

// pages/static-props.js
export async function getStaticProps() {
  try {
    const res = await fetch('https://api.example.com/data');
    const data = await res.json();

    if (!res.ok) {
      throw new Error(data.message || 'Failed to fetch data');
    }

    return {
      props: { data },
      revalidate: 10, // Revalidate at most once every 10 seconds
    };
  } catch (error) {
    console.error(error);
    return {
      props: { error: 'Failed to load data' },
    };
  }
}

const StaticPropsPage = ({ data, error }) => {
  if (error) {
    return <div>{error}</div>;
  }

  return <div>{JSON.stringify(data)}</div>;
};

export default StaticPropsPage;

Conclusion

Implementing custom error handling in Next.js involves customizing default error pages, using error boundaries for client-side errors, handling errors in API routes, logging errors for monitoring, and managing errors in data fetching methods like getServerSideProps and getStaticProps. By following these practices, you can create a robust error handling system that enhances the user experience and provides valuable insights into application issues.

To summarize:

  • Custom Error Pages: Create 404.js and 500.js in the pages directory for custom error messages.
  • Error Boundaries: Use error boundaries to catch and handle client-side errors.
  • API Routes: Implement try-catch blocks and centralized error handlers for consistent error management.
  • Logging: Integrate logging solutions like Winston or Sentry for error monitoring.
  • Data Fetching: Handle errors in getServerSideProps and getStaticProps to ensure smooth data fetching.

By incorporating these strategies, you can ensure that your Next.js application is resilient, user-friendly, and easy to maintain.

How to use Bootstrap’s utilities for hiding and showing elements

How to implement a sticky footer with a content area that scrolls

How to use Bootstrap’s form control sizing classes

How to create a responsive image carousel with captions

How to use Bootstrap’s responsive utilities for text alignment

How to implement a full-screen background image with Bootstrap

Previous
How can you optimize CSS delivery in a Next.js project
Next
What is Svelte