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

[murataslan1]

Fixes #41281

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

1. 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

2. 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

[nextjs-bot]

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]

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

[vercel]

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]

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]

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]

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]

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