nextjs

Next.js Errors

Error codes and diagnostic messages from the Next.js framework. These appear during development, at build time, and at runtime for both the App Router and Pages Router.

19 codes

references nextjs.org/docs/messages

· All codes 19 codes

cannot-override-metadata Cannot Override Metadata A child route segment attempted to override a metadata field that can only be set in the root layout, such as the viewport or the icons configuration. Some metadata fields are inherited and cannot be overridden at the segment level. Move the configuration to the root layout, or use a layout at the appropriate level in the route hierarchy.
client-only-in-server-component Client-Only in Server Component A module marked with the client-only package was imported inside a React Server Component. Modules that depend on browser APIs (DOM, window, localStorage) should only run on the client. Move the import into a component file that begins with the 'use client' directive, or wrap the usage in a Client Component.
duplicate-page Duplicate Page Two or more page files resolve to the same route. This typically happens when both a directory index file and a file with the same name exist at the same level, for example pages/about.js and pages/about/index.js. Next.js cannot determine which should take precedence, so it throws this error at startup. Remove or rename one of the conflicting files.
invalid-page-config Invalid Page Config A page file exports an invalid or unknown configuration option. In the Pages Router, only recognized exports such as getStaticProps, getServerSideProps, getStaticPaths, and config are permitted. In the App Router, valid segment config options include dynamic, revalidate, fetchCache, runtime, preferredRegion, and maxDuration. Check the export name for typos and consult the documentation for allowed values.
invalid-segment-config Invalid Segment Config A route segment file (page, layout, or route handler) exports a segment config option with an invalid value. For example, dynamic must be one of 'auto', 'force-dynamic', 'error', or 'force-static'. Supplying an unsupported value triggers this error at build time.
metadata-base-not-set Metadata Base Not Set The metadataBase property is not set in the root layout's metadata export. metadataBase is required to resolve relative URLs in metadata fields such as openGraph.images and twitter.images. Without it, relative paths cannot be turned into absolute URLs for social sharing previews. Set metadataBase to your site's origin in the root app/layout.js file.
missing-suspense-with-csr-bailout Missing Suspense with CSR Bailout A component using useSearchParams() was not wrapped in a Suspense boundary. In the App Router, useSearchParams() causes the component tree to bail out of server-side rendering and render on the client only. Without a Suspense boundary, this results in an error during build or a degraded user experience. Wrap the component (or its nearest parent that uses useSearchParams) in <Suspense fallback={...}>.
next-image-unconfigured-host Next Image Unconfigured Host The hostname of an external image URL has not been added to the remotePatterns list in next.config.js. Next.js requires you to explicitly allow external image domains for the next/image component to prevent abuse of the image optimization endpoint. Add the hostname under images.remotePatterns in your configuration.
next-script-for-ga Next Script for GA Google Analytics is being loaded via a plain <script> tag instead of the next/script component. Using next/script with the appropriate strategy avoids render-blocking behavior and improves Core Web Vitals scores. Replace the inline script with the Script component.
no-html-link-for-pages No HTML Link for Pages A raw HTML <a> element was used to link to an internal page route instead of the next/link component. Using <a> for internal navigation triggers a full page reload, losing client-side state and skipping prefetching. Replace with the Link component from 'next/link'.
no-img-element No img Element A raw HTML <img> element was used instead of the next/image component. The next/image component provides automatic image optimization, lazy loading, and prevention of Cumulative Layout Shift (CLS). Replace <img> with the Image component imported from 'next/image'.
no-page-custom-font No Page Custom Font A custom font was loaded via a <link> tag inside an individual page component instead of in the _document.js file. Fonts added per-page are re-requested on every client-side navigation. Move global font <link> tags to the <Head> inside _document.js so they are loaded once for the entire application, or use the next/font module for automatic self-hosting and optimization.
no-sync-scripts No Sync Scripts A synchronous (render-blocking) third-party <script> tag was used instead of the next/script component. Synchronous scripts block HTML parsing and delay page load. The Script component from 'next/script' provides strategy-based loading (beforeInteractive, afterInteractive, lazyOnload, worker) for optimal performance.
no-title-in-document-head No Title in Document Head A <title> element was placed inside the <Head> component in _document.js. Titles set in _document.js apply globally and cannot be overridden by individual pages. Move page-specific <title> tags into the <Head> component within each page file or use the metadata API in the App Router.
no-typos No Typos A data-fetching function export in a Pages Router page file contains a typo. Next.js recognizes only getStaticProps, getServerSideProps, and getStaticPaths by exact name. A misspelling such as getStatcProps is silently ignored at runtime, causing the page to behave as if static with no data. This lint rule catches those mistakes at development time.
no-unwanted-polyfillio No Unwanted Polyfill.io A script loading polyfills from polyfill.io is present in the application. Next.js already bundles the polyfills required by its browser support targets, making polyfill.io redundant and a potential performance and security risk (the service can inject arbitrary JavaScript). Remove the polyfill.io script tag.
react-hydration-error React Hydration Error The HTML rendered on the server does not match what React renders on the client during hydration. Common causes include using browser-only APIs (Date, Math.random, localStorage) or conditional rendering that differs between server and client. Wrap the offending component in a dynamic import with ssr: false, or use the useEffect hook to run client-only code after mount.
server-only-in-client-component Server-Only in Client Component A module marked with the server-only package was imported inside a Client Component. Modules marked server-only contain logic that must not be bundled for the browser, such as database connections or secret environment variables. Move the import to a Server Component, a server action, or a Route Handler.
sharp-missing-in-production Sharp Missing in Production The sharp package is not installed but is required for image optimization in production when self-hosting Next.js. In development Next.js uses a slower built-in optimizer, but production builds need sharp for efficient resizing. Install it with: npm install sharp