Skip to content

Conversation

@junseokku
Copy link

What?

This PR improves the confusing warning message that appears when using a custom _error page during static export (next export).

Changes:

  1. packages/next/src/server/render.tsx: Add a specific warning message for _error pages

    • Before: Generic message recommending getStaticProps for all pages
    • After: For _error pages, references the documentation that states getStaticProps is not supported and recommends using 404.js or 500.js instead
  2. docs/02-pages/03-building-your-application/01-routing/08-custom-error.mdx: Enhance documentation

    • Clarify that while getStaticProps may technically compile in _error, it has limitations
    • Add guidance on the correct data fetching pattern for static export

Why?

Currently, when running next export with a custom _error page that uses getInitialProps, Next.js displays a warning recommending the use of getStaticProps. However, according to the documentation, _error pages do not support getStaticProps, which causes confusion for developers.

Problem:

  • Custom _error page with getInitialProps → warning appears
  • Warning message recommends using getStaticProps
  • The documentation states that getStaticProps is not supported in _error pages
  • Developers experience frustration trying to follow the recommendation that contradicts the documentation

How?

  1. Warning message branching:

    • Display a specific warning message when pathname === '/_error'
    • Reference the documentation that states _error pages do not support getStaticProps
    • Recommend using 404.js or 500.js as alternatives
  2. Documentation enhancement:

    • Add explanation of technical limitations of getStaticProps in the Caveats section
    • Provide guidance on the correct pattern for static export

- Enhanced documentation in `08-custom-error.mdx` to clarify that `getStaticProps` is not supported in custom error pages and recommended using `pages/404.js` or `pages/500.js` for data fetching.
- Updated warning messages in `render.tsx` to specify that using `getInitialProps` in `pages/_error` is discouraged and to suggest alternatives for static error pages.

These changes aim to improve clarity and guidance for developers regarding error handling in Next.js applications.
@nextjs-bot nextjs-bot added Documentation Related to Next.js' official documentation. type: next labels Jan 7, 2026
@nextjs-bot
Copy link
Collaborator

Allow CI Workflow Run

  • approve CI run for commit: a7ace7e

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation Related to Next.js' official documentation. type: next

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants