Note: You are viewing the new Next.js documentation. The old docs are still available here.

Custom Error Page

404 or 500 errors are handled both client-side and server-side by the Error component. If you wish to override it, define the file pages/_error.js and add the following code:

function Error({ statusCode }) {
  return (
        ? `An error ${statusCode} occurred on server`
        : 'An error occurred on client'}

Error.getInitialProps = ({ res, err }) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404
  return { statusCode }

export default Error

pages/_error.js is only used in production. In development you'll get an error with the call stack to know where the error originated from.

Reusing the built-in error page permalink

If you want to render the built-in error page you can by importing the Error component:

import Error from 'next/error'
import fetch from 'isomorphic-unfetch'

const Page = ({ errorCode, stars }) => {
  if (errorCode) {
    return <Error statusCode={errorCode} />

  return <div>Next stars: {stars}</div>

Page.getInitialProps = async () => {
  const res = await fetch('')
  const errorCode = res.statusCode > 200 ? res.statusCode : false
  const json = await res.json()

  return { errorCode, stars: json.stargazers_count }

export default Page

The Error component also takes title as a property if you want to pass in a text message along with a statusCode.