Better error log for router state header in parseAndValidateFlightRouterState

[Luk-z]

None of next.js dev answer this issue. To have a decent error-logging experience i think it is useful adding some info about the error.

Probably the error is caused by a malformed stateHeader and printing this information in the error message is a smart way to know what's happening.

Merging this PR would be a good deed towards all people stuck with this error log.

---

I used stateHeader.substring(0, 1000) to limit the chars printed but You can use whatever you want to achieve this. The important thing is to have a message that makes it clear whats happening

[nextjs-bot]

Allow CI Workflow Run

• [ ] approve CI run for commit: 02d52e62ec1a4cf082edc18476c61f302597799e

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

[harikapadia999]

Great improvement to error diagnostics! 🎯

What This Fixes: Makes debugging router state header issues much easier by including actual data in error messages instead of generic errors.

Strengths: ✅ Includes header length for "multiple headers" error
✅ Shows first 1000 chars of problematic header for debugging
✅ Helps developers understand what went wrong

Suggestions for Enhancement:

1. Security Consideration: The router state header might contain sensitive data (URLs, params, etc.). Consider:

   // Redact potentially sensitive data
   const sanitizedHeader = stateHeader.substring(0, 1000).replace(/[?&]([^=&]+)=([^&]*)/g, (match, key) => {
     // Keep structure but hide values
     return `${key}=[REDACTED]`
   })
   

2. Better Truncation Indicator: Add clear truncation marker:

   `The router state header was too large (stateHeader=${stateHeader.substring(0, 1000)}${stateHeader.length > 1000 ? '... [truncated]' : ''}).`
   

3. Include Actual Size: For the "too large" error, show the actual size vs limit:

   `The router state header was too large (${stateHeader.length} bytes, max: ${MAX_SIZE} bytes). Preview: ${stateHeader.substring(0, 1000)}...`
   

4. Parse Error Details: For the parse error, consider catching and including the JSON parse error message:

   } catch (parseError) {
     throw new Error(
       `The router state header was sent but could not be parsed. Error: ${parseError.message}. Header preview: ${stateHeader.substring(0, 1000)}...`
     )
   }
   

Overall, this is a valuable DX improvement! The suggestions above would make it even more helpful while maintaining security. 🚀

[Luk-z]

@harikapadia999 done