fix(build): improve error message for non-string params in getStaticPaths by murataslan1 · Pull Request #89389 · vercel/next.js

murataslan1 · 2026-02-02T12:16:02Z

Problem

When getStaticPaths receives a non-string parameter, the error message was not helpful:

A required parameter (id) was not provided as a string received number

Solution

Enhanced error message in static-paths/pages.ts:
- Changed from Error to TypeError for type-related issues
- Shows the actual value received (when applicable)
- Provides clear example of correct usage
- Links to documentation
Added type check in escapePathDelimiters:
- Validates that segment is a string before calling .replace()
- Provides clear error message pointing to getStaticPaths

After this fix

A required parameter (id) was not provided as a string in getStaticPaths for /posts/[id].
Received: number (123)

Make sure to provide the parameter as a string. For example:
  { params: { id: "value" } }

See: https://nextjs.org/docs/messages/invalid-getstaticpaths-value

Made with Cursor

…aths Fixes vercel#41281 Improved the error handling for getStaticPaths when non-string parameters are provided: 1. Enhanced error message in pages.ts: - Changed from Error to TypeError for type-related issues - Shows the actual value received (when applicable) - Provides clear example of correct usage - Links to documentation 2. Added type check in escapePathDelimiters: - Validates that segment is a string before calling .replace() - Provides clear error message pointing to getStaticPaths Before: 'A required parameter (id) was not provided as a string received number' After: 'A required parameter (id) was not provided as a string in getStaticPaths. Received: number (123) Make sure to provide the parameter as a string. For example: { params: { id: "value" } }' Co-authored-by: Cursor <[email protected]>

nextjs-bot · 2026-02-02T12:16:24Z

Allow CI Workflow Run

approve CI run for commit: 0add2a3

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

nextjs-bot · 2026-02-02T12:16:25Z

Allow CI Workflow Run

approve CI run for commit: 4ddcd8b

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

vercel · 2026-02-02T12:23:30Z

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

+              : Array.isArray(paramValue)
+                ? 'an array'
+                : typeof paramValue
+          throw new TypeError(


Test assertions use old error message format that doesn't match the new improved error format in pages.ts

Copilot

Pull request overview

This PR improves error messages when getStaticPaths receives non-string parameters, addressing issue #41281. The changes enhance developer experience by providing clearer, more actionable error messages with examples and documentation links.

Changes:

Enhanced error message in static-paths/pages.ts to use TypeError, show actual received values, and provide usage examples
Added defensive type check in escapePathDelimiters to validate string parameters

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
packages/next/src/build/static-paths/pages.ts	Improved error message for invalid parameter types with detailed feedback including received value, expected format, usage example, and documentation link
packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts	Added runtime type validation to ensure segment parameter is a string before processing

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-02T12:24:27Z

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

-            `A required parameter (${validParamKey}) was not provided as ${
-              repeat ? 'an array' : 'a string'
-            } received ${typeof paramValue} in getStaticPaths for ${page}`
+          const expectedType = repeat ? 'an array of strings' : 'a string'


The error message says "an array of strings" but the validation check repeat && !Array.isArray(paramValue) only verifies that the value is an array, not that all its elements are strings. This creates a mismatch between what the error message promises and what the code actually validates. After adding validation for array elements being strings, this message will be accurate.

Copilot · 2026-02-02T12:24:28Z

packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts

+      `Expected a string for path segment, but received ${
+        segment === null ? 'null' : typeof segment
+      }. ` +
+        `Ensure all path parameters in getStaticPaths are strings.`


The error message mentions "getStaticPaths" but this function is also used in runtime contexts (e.g., in decode-path-params.ts for runtime path decoding). The error message should be more generic since it's not exclusively related to getStaticPaths. Consider updating the message to something like: "Expected a string for path segment, but received ${segment === null ? 'null' : typeof segment}."

Suggested change

`Ensure all path parameters in getStaticPaths are strings.`

`Ensure all path parameters are strings.`

Copilot · 2026-02-02T12:24:28Z

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

+          throw new TypeError(
+            `A required parameter (${validParamKey}) was not provided as ${expectedType} in getStaticPaths for ${page}.\n` +
+              `Received: ${receivedType}${typeof paramValue !== 'undefined' && paramValue !== null ? ` (${JSON.stringify(paramValue)})` : ''}\n` +


Using JSON.stringify without error handling could cause the error message construction itself to fail if paramValue contains circular references or other non-serializable values (functions, symbols, etc.). Consider wrapping it in a try-catch block or using a safer approach. For example:

let valueDisplay = '' try { valueDisplay = ` (${JSON.stringify(paramValue)})` } catch { valueDisplay = ` (${String(paramValue)})` }

This ensures the error message is always shown, even if the value can't be stringified.

Suggested change

throw new TypeError(

`A required parameter (${validParamKey}) was not provided as ${expectedType} in getStaticPaths for ${page}.\n` +

`Received: ${receivedType}${typeof paramValue !== 'undefined' && paramValue !== null ? ` (${JSON.stringify(paramValue)})` : ''}\n` +

let receivedValueDisplay = ''

if (typeof paramValue !== 'undefined' && paramValue !== null) {

try {

receivedValueDisplay = ` (${JSON.stringify(paramValue)})`

} catch {

receivedValueDisplay = ` (${String(paramValue)})`

}

}

throw new TypeError(

`A required parameter (${validParamKey}) was not provided as ${expectedType} in getStaticPaths for ${page}.\n` +

`Received: ${receivedType}${receivedValueDisplay}\n` +

lukesandberg · 2026-02-04T01:09:43Z

The bot commants all seem quite relevant. please address those and feel free to add me as a reviewer when they are addressed

- Add try-catch wrapper around JSON.stringify to prevent crashes on circular references - Generalize error message in escape-path-delimiters.ts (remove 'in getStaticPaths') - Update test assertions to match new error message format

murataslan1 · 2026-02-20T18:28:47Z

Superseded by #89389 (comment) (previous comment was malformed by shell escaping).

murataslan1 · 2026-02-20T18:30:01Z

Addressed the bot feedback in commit 5dad8b4:

getStaticPaths catch-all validation now enforces arrays of strings (not just arrays).
Updated integration assertions to match the current error format (Received: ... + trailing period).
Added a regression test for non-string catch-all arrays (slug: [123]).

I also regenerated packages/next/errors.json via the standard build/check flow. Please re-review when convenient.

murataslan1 · 2026-02-27T20:33:41Z

@lukesandberg Addressed the bot feedback in the latest commits. Ready for another look when you get a chance. Thanks!

Copilot AI review requested due to automatic review settings February 2, 2026 12:16

nextjs-bot added the type: next label Feb 2, 2026

Copilot started reviewing on behalf of murataslan1 February 2, 2026 12:16 View session

vercel bot reviewed Feb 2, 2026

View reviewed changes

Copilot AI reviewed Feb 2, 2026

View reviewed changes

fix: address PR review feedback

4ddcd8b

- Add try-catch wrapper around JSON.stringify to prevent crashes on circular references - Generalize error message in escape-path-delimiters.ts (remove 'in getStaticPaths') - Update test assertions to match new error message format

nextjs-bot added the tests label Feb 4, 2026

fix(build): validate string arrays in getStaticPaths params

5dad8b4

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(build): improve error message for non-string params in getStaticPaths#89389

fix(build): improve error message for non-string params in getStaticPaths#89389
murataslan1 wants to merge 3 commits intovercel:canaryfrom
murataslan1:fix/getstaticpaths-error-message

murataslan1 commented Feb 2, 2026

Uh oh!

nextjs-bot commented Feb 2, 2026

Uh oh!

nextjs-bot commented Feb 2, 2026 •

edited

Loading

Uh oh!

vercel bot Feb 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

lukesandberg commented Feb 4, 2026

Uh oh!

murataslan1 commented Feb 20, 2026 •

edited

Loading

Uh oh!

murataslan1 commented Feb 20, 2026

Uh oh!

murataslan1 commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	`Ensure all path parameters in getStaticPaths are strings.`
	`Ensure all path parameters are strings.`

-          throw new TypeError(
-            `A required parameter (${validParamKey}) was not provided as ${expectedType} in getStaticPaths for ${page}.\n` +
-              `Received: ${receivedType}${typeof paramValue !== 'undefined' && paramValue !== null ? ` (${JSON.stringify(paramValue)})` : ''}\n` +
+          let receivedValueDisplay = ''
+          if (typeof paramValue !== 'undefined' && paramValue !== null) {
+            try {
+              receivedValueDisplay = ` (${JSON.stringify(paramValue)})`
+            } catch {
+              receivedValueDisplay = ` (${String(paramValue)})`
+            }
+          }
+          throw new TypeError(
+            `A required parameter (${validParamKey}) was not provided as ${expectedType} in getStaticPaths for ${page}.\n` +
+              `Received: ${receivedType}${receivedValueDisplay}\n` +

Conversation

murataslan1 commented Feb 2, 2026

Problem

Solution

After this fix

Uh oh!

nextjs-bot commented Feb 2, 2026

Uh oh!

nextjs-bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

lukesandberg commented Feb 4, 2026

Uh oh!

murataslan1 commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

murataslan1 commented Feb 20, 2026

Uh oh!

murataslan1 commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nextjs-bot commented Feb 2, 2026 •

edited

Loading

murataslan1 commented Feb 20, 2026 •

edited

Loading