Throw when generateStaticParams returns incomplete params with output: export

Author: devjiwonchoi

errors/generate-static-params.mdx

@@ -29,10 +29,13 @@ When your application uses `output: 'export'`, every [Dynamic Route](/docs/app/a
 
 This error also occurs when a dynamic route:
 
-- does not export a `generateStaticParams` function, or
-- returns an empty array from `generateStaticParams`.
+- does not export a `generateStaticParams` function,
+- returns an empty array from `generateStaticParams`, or
+- generates a route without every dynamic route parameter. For example, `{ slug: 'first' }` does not provide the `id` value for a route using an `[id]` segment.
 
-Export `generateStaticParams` from every dynamic route and return at least one params object. If the paths cannot be known at build time, remove `output: 'export'` from your Next.js configuration.
+When multiple route segments export `generateStaticParams`, Next.js combines the params returned by each parent and child function before generating routes.
+
+Export `generateStaticParams` from every dynamic route and make sure the combined params include all dynamic route parameters for every generated route. If the paths cannot be known at build time, remove `output: 'export'` from your Next.js configuration.
 
 ## Useful Links
 

packages/next/errors.json

@@ -1451,5 +1451,6 @@
   "1450": "Invalid value at index %s returned from generateStaticParams for \"%s\". Expected an object, but received type %s. See more info here: https://nextjs.org/docs/messages/generate-static-params",
   "1451": "Page \"%s\" is missing \"generateStaticParams()\" so it cannot be used with \"output: export\" config. See more info here: https://nextjs.org/docs/messages/generate-static-params",
   "1452": "Page \"%s\" is missing exported function \"generateStaticParams()\", which is required with \"output: export\" config. See more info here: https://nextjs.org/docs/messages/generate-static-params",
-  "1453": "Page \"%s\" returned an empty array from \"generateStaticParams()\". With \"output: export\", at least one route must be generated. See more info here: https://nextjs.org/docs/messages/generate-static-params"
+  "1453": "Page \"%s\" returned an empty array from \"generateStaticParams()\". With \"output: export\", at least one route must be generated. See more info here: https://nextjs.org/docs/messages/generate-static-params",
+  "1454": "Page \"%s\" returned incomplete params from \"generateStaticParams()\". With \"output: export\", every params object must include all dynamic route parameters. Missing: %s. See more info here: https://nextjs.org/docs/messages/generate-static-params"
 }

packages/next/src/build/static-paths/app.ts

@@ -977,17 +977,29 @@ export async function buildAppStaticPaths({
     }
   }
 
+  const missingParamNames: string[] = []
+  if (routeParams.length > 0) {
+    for (const { paramName } of pathnameRouteParamSegments) {
+      if (routeParams.some((params) => !(paramName in params))) {
+        missingParamNames.push(paramName)
+      }
+    }
+  }
+
   // Determine if all the segments have had their parameters provided.
   const hadAllParamsGenerated =
     pathnameRouteParamSegments.length === 0 ||
-    (routeParams.length > 0 &&
-      routeParams.every((params) => {
-        for (const { paramName } of pathnameRouteParamSegments) {
-          if (paramName in params) continue
-          return false
-        }
-        return true
-      }))
+    (routeParams.length > 0 && missingParamNames.length === 0)
+
+  if (
+    nextConfigOutput === 'export' &&
+    routeParams.length > 0 &&
+    !hadAllParamsGenerated
+  ) {
+    throw new Error(
+      `Page "${page}" returned incomplete params from "generateStaticParams()". With "output: export", every params object must include all dynamic route parameters. Missing: ${missingParamNames.map((name) => `"${name}"`).join(', ')}. See more info here: https://nextjs.org/docs/messages/generate-static-params`
+    )
+  }
 
   // TODO: dynamic params should be allowed to be granular per segment but
   // we need additional information stored/leveraged in the prerender

test/e2e/app-dir-export/test/dynamic-missing-gsp.test.ts

@@ -39,6 +39,24 @@ describe('app dir - with output export - dynamic missing gsp', () => {
     })
   })
 
+  describe('should error when generateStaticParams returns incomplete params', () => {
+    runTests({
+      dynamicPage: 'undefined',
+      generateStaticParamsOpt: 'set wrong param',
+      expectedErrMsg:
+        'Page "/another/[slug]" returned incomplete params from "generateStaticParams()". With "output: export", every params object must include all dynamic route parameters. Missing: "slug". See more info here: https://nextjs.org/docs/messages/generate-static-params',
+    })
+  })
+
+  describe('should error when one of the generated params is incomplete', () => {
+    runTests({
+      dynamicPage: 'undefined',
+      generateStaticParamsOpt: 'set mixed params',
+      expectedErrMsg:
+        'Page "/another/[slug]" returned incomplete params from "generateStaticParams()". With "output: export", every params object must include all dynamic route parameters. Missing: "slug". See more info here: https://nextjs.org/docs/messages/generate-static-params',
+    })
+  })
+
   describe('should error when client component has generateStaticParams', () => {
     const expectedErrMsg = process.env.IS_TURBOPACK_TEST
       ? 'App pages cannot use both "use client" and export function "generateStaticParams()".'

test/e2e/app-dir-export/test/utils.ts

@@ -222,7 +222,9 @@ export function runTests({
     | 'set client'
     | 'set empty'
     | 'set invalid entry'
+    | 'set mixed params'
     | 'set non-array'
+    | 'set wrong param'
   expectedErrMsg?: string | RegExp
 }) {
   let { next, skipped, isNextDev } = nextTestSetup({
@@ -302,6 +304,20 @@ export function runTests({
           'return []'
         )
       )
+    } else if (generateStaticParamsOpt === 'set wrong param') {
+      await next.patchFile('app/another/[slug]/page.js', (content) =>
+        content.replace(
+          `return [{ slug: 'first' }, { slug: 'second' }]`,
+          `return [{ id: 'first' }]`
+        )
+      )
+    } else if (generateStaticParamsOpt === 'set mixed params') {
+      await next.patchFile('app/another/[slug]/page.js', (content) =>
+        content.replace(
+          `return [{ slug: 'first' }, { slug: 'second' }]`,
+          `return [{ slug: 'first' }, { id: 'second' }]`
+        )
+      )
     }
   })