-
Notifications
You must be signed in to change notification settings - Fork 26.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Improve some of the error messages pages. (#52271)
Now that we've improved `/messages` (#52038), we'd like to start updating some of the content as well 🙏
- Loading branch information
Showing
13 changed files
with
115 additions
and
70 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,21 @@ | ||
--- | ||
title: 404.js Cannot Have getInitialProps | ||
description: This document provides an understanding of the "404.js Cannot Have getInitialProps" error in Next.js and offers solutions to fix it. | ||
--- | ||
|
||
## Why This Error Occurred | ||
|
||
In your `404.js` page you added `getInitialProps` or `getServerSideProps` which is not allowed as this prevents the page from being static and `404.js` is meant to provide more flexibility for a static 404 page. Having a static 404 page is the most ideal as this page can be served very often and if not static puts extra strain on your server and more invocations for serverless functions which increase the cost of hosting your site unnecessarily. | ||
The "404.js Cannot Have `getInitialProps`" error usually occurs when either `getInitialProps` or `getServerSideProps` is used in your `404.js` page. The `404.js` page in Next.js is designed to be static to ensure consistent performance. | ||
|
||
## Possible Ways to Fix It | ||
|
||
Remove `getInitialProps` from `404.js` and make sure no HOC's used in `404.js` attach `getInitialProps`. | ||
Adding `getInitialProps` or `getServerSideProps` to your `404.js` page will cause it to be rendered on the server-side. | ||
|
||
If you want to fetch data for your `404.js` page move it to a client side fetch inside of `componentDidMount` or `useEffect(() => {}, [])`. | ||
To fix this error, you should remove `getInitialProps` from your `404.js` page. Additionally, ensure that no Higher-Order Components (HOCs) used in the `404.js` page are attaching `getInitialProps`. | ||
|
||
If your `404.js` page requires data fetching, we recommend incrementall adopting the App Router and the [`not-found`](/docs/app/api-reference/file-conventions/not-found) file, which does support fetching data before displaying the 404 page. | ||
|
||
## Useful Links | ||
|
||
- [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization) | ||
- [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization) - Learn more about how Next.js automatically optimizes your pages for better performance. | ||
- [`not-found`](/docs/app/api-reference/file-conventions/not-found) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,16 +1,19 @@ | ||
--- | ||
title: AMP Bind JSX Error | ||
title: Resolving "AMP Bind JSX Error" in Next.js | ||
description: This document explains the "AMP Bind JSX Error" in Next.js and provides a valid solution to resolve it. | ||
--- | ||
|
||
## Why This Error Occurred | ||
|
||
Somewhere you used `[prop]='something'` syntax which is not allowed in JSX. | ||
The "AMP Bind JSX Error" arises when you use the `[prop]='something'` syntax somewhere in your code. | ||
|
||
JSX is a syntax extension for JavaScript used by React (and by extension, Next.js). JSX does not support the usage of this particular syntax, hence the error. | ||
|
||
## Possible Ways to Fix It | ||
|
||
Instead you can use `data-amp-bind-prop='something'` which is a valid AMP alternative | ||
To fix this issue, instead of using `[prop]='something'`, you can use `data-amp-bind-prop='something'`. This is a valid alternative in Accelerated Mobile Pages (AMP) that works well with JSX. | ||
|
||
## Useful Links | ||
|
||
- [AMP HTML Specification](https://www.ampproject.org/docs/fundamentals/spec) | ||
- [Possible future syntax](https:/ampproject/amphtml/issues/21600) | ||
- [AMP HTML Specification](https://www.ampproject.org/docs/fundamentals/spec) - Understand the underlying standards and rules for creating AMP pages. | ||
- [Possible future syntax](https:/ampproject/amphtml/issues/21600) - Check out the discussions on potential syntax changes that may be applicable in the future. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,18 @@ | ||
--- | ||
title: AMP Export Validation | ||
title: Troubleshooting "AMP Export Validation" Error in Next.js | ||
description: This document provides insights on the "AMP Export Validation" error in Next.js and how to address it. | ||
--- | ||
|
||
## Why This Error Occurred | ||
|
||
During export we validate AMP pages using [amphtml-validator](https://www.npmjs.com/package/amphtml-validator). Errors received from the validator will fail the export. | ||
The "AMP Export Validation" error typically occurs during the export process when the AMP pages are validated using the [amphtml-validator](https://www.npmjs.com/package/amphtml-validator). If the validator returns any errors, the export process will fail. | ||
|
||
Validation errors will cause pages to not be [indexed by AMP Caches](https://www.ampproject.org/docs/fundamentals/how_cached). | ||
AMP validation errors are crucial as they can prevent your pages from being indexed by AMP Caches. AMP Caches are systems that store and serve valid AMP documents to ensure faster delivery of AMP pages to users. | ||
|
||
## Possible Ways to Fix It | ||
|
||
Look at the error messages and follow their appropriate links to learn more about the error and how to correct the problem. | ||
To resolve this issue, carefully review the error messages provided by the validator. These messages usually provide detailed insights into the problem and how to fix it. Following the links associated with these error messages can also guide you to more information about the particular error and its solution. | ||
|
||
## Useful Links | ||
|
||
- [AMP HTML Specification](https://www.ampproject.org/docs/fundamentals/spec) | ||
- [AMP HTML Specification](https://www.ampproject.org/docs/fundamentals/spec) - Get more details about AMP standards and conventions to ensure your pages are compliant. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,23 @@ | ||
--- | ||
title: API routes in Static export | ||
title: Understanding "API Routes in Static Export" Warning in Next.js | ||
description: This document explains the "API Routes in Static Export" warning in Next.js and offers steps to resolve it. | ||
--- | ||
|
||
#### Why This Warning Occurred | ||
## Why This Warning Occurred | ||
|
||
An `exportPathMap` path was matched to an API route. Statically exporting a Next.js application via `next export` disables API routes. | ||
The "API Routes in Static Export" warning is typically raised when an `exportPathMap` path is matched to an API route while trying to statically export a Next.js application via the `next export` command. This command disables API routes as it is designed for a static-only setup. | ||
|
||
This command is meant for a static-only setup, and is not necessary to make your application static. Pages in your application without server-side data dependencies will be automatically statically exported by `next build`, including pages powered by `getStaticProps` | ||
Running `next export` is not necessary to make your application static. Pages in your application that do not have server-side data dependencies will be automatically statically optimized when you run `next build`. This includes pages powered by `getStaticProps`. | ||
|
||
## Possible Ways to Fix It | ||
|
||
Use `next build` with platforms that don't require `next export` like https://vercel.com or remove any paths using API routes from your `exportPathMap` in `next.config.js`. | ||
To resolve this issue, you have two main options: | ||
|
||
1. Use the `next build` command instead of `next export` if you're deploying your application on platforms that don't require `next export`. For example, [Vercel](https://vercel.com) is a popular hosting platform for Next.js applications that supports this feature. | ||
2. If you still need to use `next export`, make sure to remove any paths that use API routes from your `exportPathMap` in your `next.config.js` file. | ||
3. Consider [incrementally adopting the App Router](/docs/app/building-your-application/upgrading/app-router-migration), which supportes [Route Handlers](/docs/app/building-your-application/routing/router-handlers). These "API Routes" can be used to create endpoints that can be statically exported in your application. | ||
|
||
## Useful Links | ||
|
||
- [Static HTML export](/docs/pages/building-your-application/deploying/static-exports) | ||
- [Static HTML export](/docs/pages/building-your-application/deploying/static-exports) - Learn more about how you can create a static HTML export of your Next.js application. | ||
- [Route Handlers](/docs/app/building-your-application/routing/router-handlers) - Learn more about how you can use Route Handlers to create endpoints that can be statically exported in your application. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,20 +1,23 @@ | ||
--- | ||
title: 'App Router Static to Dynamic Error' | ||
title: Resolving "app/ Static to Dynamic Error" in Next.js | ||
description: This document explains the "app/ Static to Dynamic Error" in Next.js and provides potential solutions to resolve it. | ||
--- | ||
|
||
## Why This Error Occurred | ||
|
||
Inside one of your `app/` pages, the page was initially generated statically at build time, and then during runtime either a fallback path or path being revalidated attempted to leverage dynamic server values e.g. `cookies()` or `headers()`. | ||
The "`app/` Static to Dynamic Error" happens when one of your routes in the `app/` directory is initially generated statically at build time, but during runtime it attempts to use dynamic server values (such as `cookies()` or `headers()`) either for a fallback path or while a path is being revalidated. | ||
|
||
This is a hard error by default as a path generated statically can't switch between types during runtime currently. | ||
Currently, Next.js does not support switching between static and dynamic types during runtime, so the system throws an error. | ||
|
||
## Possible Ways to Fix It | ||
|
||
Prevent usage of these dynamic server values conditionally which can cause the static/dynamic mode of the page to differ between build time and runtime. | ||
To resolve this issue, you have two main options: | ||
|
||
Leverage `export const dynamic = 'force-static'` to ensure the page is handled statically regardless of the usage of dynamic server values. Alternatively, if you prefer your page to always be dynamic you can set `export const dynamic = 'force-dynamic'` and it won't attempt to have the page be statically generated. | ||
1. Prevent the conditional use of dynamic server values that may cause the static/dynamic mode of the page to differ between build time and runtime. This ensures consistency in the rendering mode of your page. | ||
|
||
2. Leverage the `dynamic` export to control the handling of your page. If you want to ensure your page is always handled statically, regardless of the usage of dynamic server values, you can use `export const dynamic = 'force-static'`. Conversely, if you prefer your page to always be dynamic, you can use `export const dynamic = 'force-dynamic'`, and your page won't attempt to be statically generated. | ||
|
||
## Useful Links | ||
|
||
- [static/dynamic rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering) | ||
- [dynamic server value methods](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions) | ||
- [Static and Dynamic Rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering) - Learn more about the differences between static and dynamic rendering in Next.js. | ||
- [Dynamic Functions](/docs/app/building-your-application/data-fetching/fetching#server-component-functions) - Understand more about the usage of dynamic server functions in your Next.js application. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,16 +1,17 @@ | ||
--- | ||
title: 'Babel and `next/font` conflict' | ||
title: Resolving "Babel and `next/font` Conflict" in Next.js | ||
description: This document explains the "Babel and `next/font` Conflict" in Next.js and provides a solution to resolve this issue. | ||
--- | ||
|
||
## Why This Error Occurred | ||
|
||
You have tried to use `next/font` with a custom babel config. When your application has a custom babel config you opt-out of the Next.js Compiler which is required to use `next/font`. | ||
The "Babel and `next/font` Conflict" error arises when you attempt to use `next/font` in conjunction with a custom Babel configuration in your Next.js application. When you have a custom Babel config, you opt out of the Next.js Compiler, which is a requirement for using `next/font`. | ||
|
||
## Possible Ways to Fix It | ||
|
||
- Remove your custom babel config and use the Next.js Compiler | ||
To address this issue, you should remove your custom Babel configuration (e.g. `.babelrc`) and instead make use of the Next.js Compiler. This ensures compatibility between your Babel configuration and `next/font`. | ||
|
||
## Useful Links | ||
|
||
- [Next.js Compiler](/docs/architecture/nextjs-compiler) | ||
- [Customizing Babel Config](/docs/pages/building-your-application/configuring/babel) | ||
- [Next.js Compiler](/docs/architecture/nextjs-compiler) - Learn more about the Next.js Compiler and how it benefits your application. | ||
- [Customizing Babel Config](/docs/pages/building-your-application/configuring/babel) - Understand more about how to customize your Babel configuration in a Next.js application, and the implications of doing so. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,18 @@ | ||
--- | ||
title: Beta Middleware Used | ||
title: Addressing "Beta Middleware Used" Error in Next.js | ||
description: This document clarifies the "Beta Middleware Used" error in Next.js and provides a potential solution to fix it. | ||
--- | ||
|
||
## Why This Error Occurred | ||
|
||
[Middleware](/docs/pages/building-your-application/routing/middleware) was beta in versions prior to `v12.2` and not yet covered by [semver](https://semver.org/). | ||
The "Beta Middleware Used" error occurs if you are using [Middleware](/docs/pages/building-your-application/routing/middleware) in a version of Next.js prior to `v12.2`. The Middleware feature was still in beta in those versions and not yet covered by [semver](https://semver.org/) or Semantic Versioning rules. | ||
|
||
## Possible Ways to Fix It | ||
|
||
You can continue to use Middleware in versions prior to `v12.2`. However, you will need to make changes to upgrade to newer versions. | ||
Despite this error, you can continue using Middleware in versions prior to `v12.2`. Be aware that **upgrading to newer versions of Next.js will require changes to your application to accommodate updates in Middleware handling**. | ||
|
||
If you're using Next.js on Vercel, your existing deploys using Middleware will continue to work, and you can continue to deploy your site using Middleware. When you upgrade your site to `v12.2` or later, you will need to follow the [upgrade guide](/docs/messages/middleware-upgrade-guide). | ||
If you're using Next.js on Vercel, your existing deployments using Middleware will remain functional, and you can keep deploying your site with Middleware. However, when you decide to upgrade your site to Next.js `v12.2` or later, you'll need to follow the provided [upgrade guide](/docs/messages/middleware-upgrade-guide) to ensure compatibility. | ||
|
||
## Useful Links | ||
|
||
- [Middleware Upgrade Guide](/docs/messages/middleware-upgrade-guide) | ||
- [Middleware Upgrade Guide](/docs/messages/middleware-upgrade-guide) - Learn more about the necessary steps to upgrade your application to a version of Next.js that includes the official version of Middleware. |
Oops, something went wrong.