[Bug] Next.js 15.5.3 + React 19 RC - Build fails with React error #31 during static generation #84283
Description
[BUG] Next.js 15.5.3 + React 19.0.0 RC - Build fails with "React error #31" during static generation
Description
Production build fails during static generation of error pages (404, 500) with React error #31: "Objects are not valid as a React child". The application works perfectly in development mode and at runtime, but npm run build fails consistently during the static generation phase.
Environment
- Next.js: 15.5.3
- React: 19.0.0 (RC)
- React-DOM: 19.0.0 (RC)
- Node: 20.x
- OS: Linux 5.15.0-151-generic
- Package Manager: npm
- Deployment Target: Standalone output
Error Message
[Error: Minified React error #31; visit https://reactjs.org/docs/error-decoder.html?invariant=31&args[]=object%20with%20keys%20%7B%24%24typeof%2C%20type%2C%20key%2C%20ref%2C%20props%7D for the full message or use the non-minified dev environment for full errors and additional helpful warnings.]
Error occurred prerendering page "/404". Read more: https://nextjs.org/docs/messages/prerender-error
Export encountered an error on /_error: /404, exiting the build.
Minimal Reproduction
- Create a new Next.js 15 app with React 19 RC:
npx create-next-app@latest my-app
cd my-app
npm install react@rc react-dom@rc- Create a basic layout with any client component:
// app/layout.tsx
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: 'Test App',
}
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}- Run build:
npm run buildExpected Behavior
Build should complete successfully and generate static pages.
Actual Behavior
Build fails during static generation with React error #31, specifically when trying to prerender error pages (404, 500).
Investigation & Findings
The Issue is NOT Related To:
-
Authentication Providers (Clerk, NextAuth, etc.)
- Error persists even with NO authentication provider
- Removed all ClerkProvider components - still fails
-
Error Boundary Components
- Deleted all custom error.tsx, not-found.tsx, global-error.tsx files
- Error still occurs with Next.js default error pages
-
Font Loading
- Removed next/font/google Inter font
- Error persists without any font imports
-
CSS/Styling
- Removed all CSS imports including globals.css
- Error persists with no styles
-
Client Components
- Made everything server components
- Error still occurs
Root Cause
This appears to be a fundamental incompatibility between React 19 RC and Next.js 15's static generation process. The error occurs during the serialization phase when Next.js attempts to statically generate pages, suggesting React 19 RC has breaking changes in how it handles object serialization during SSR/SSG.
Attempted Solutions (All Failed)
1. Dynamic Rendering Configuration
export const dynamic = 'force-dynamic'Result: No effect, error persists
2. Suspense Boundaries
<Suspense fallback={<div>Loading...</div>}>
{children}
</Suspense>Result: No effect, error persists
3. Conditional Client-Side Rendering
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return nullResult: No effect during build phase
4. Next.js Configuration Changes
// next.config.js
{
output: 'standalone',
experimental: {
serverComponentsExternalPackages: ['@clerk/nextjs'],
}
}Result: No effect, error persists
5. Custom Error Pages with Dynamic Imports
// pages/404.js, pages/500.js
export default function Custom404() {
return <h1>404</h1>
}Result: Error still occurs
6. Webpack Configuration
webpack: (config, { isServer }) => {
if (!isServer) {
config.resolve.fallback = { fs: false }
}
return config
}Result: No effect
Workarounds That DO Work
1. Deploy to Vercel/Netlify
These platforms handle the SSG issue in their build infrastructure automatically.
2. Use Development Mode
npm run devEverything works perfectly in development mode.
3. Use Standalone Build Despite Error
npm run build || true
node .next/standalone/server.jsThe build fails but still creates a working standalone output.
4. Downgrade to React 18
npm install react@18 react-dom@18 @types/react@18 @types/react-dom@18This should resolve the issue but may break other React 19 features if you're using them.
Impact
- Development: No impact, works perfectly
- CI/CD: Builds fail, breaking automated deployments
- Production Runtime: No impact once deployed (app works fine)
- Developer Experience: Confusing error that appears to be auth-related but isn't
Related Issues
- This may be related to React 19 RC's changes to SSR/SSG serialization
- Similar issues might exist in other Next.js + React 19 RC projects
- Not specific to any authentication library (Clerk, Auth.js, etc.)
Suggested Fix
- Next.js should handle React 19 RC's serialization changes during SSG
- Or provide clear documentation about React 19 RC incompatibility
- Or provide a configuration option to bypass SSG for error pages
Additional Context
- The error is misleading as it suggests an issue with rendering objects as React children
- Many developers will waste time debugging authentication providers when that's not the issue
- The app is fully functional despite the build error
- This affects any Next.js 15 project using React 19 RC
System Information
{
"next": "15.5.3",
"react": "19.0.0",
"react-dom": "19.0.0",
"node": "20.x",
"platform": "linux"
}Package.json Dependencies
{
"dependencies": {
"next": "^15.5.3",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
"devDependencies": {
"@types/react": "^19.0.2",
"@types/react-dom": "^19.0.2",
"typescript": "^5.9.2"
}
}Note: This issue is NOT related to Clerk, NextAuth, or any other authentication library. It's a core incompatibility between React 19 RC and Next.js 15's static generation process.