`router.replace()` restores initial URL query params/hash when replacing with a bare path

Why this is a good first issue

The issue involves unexpected URL query parameter behavior in production.

AI Summary

The issue describes a bug where `router.replace('/')` in the App Router unexpectedly restores query parameters from the initial URL session instead of navigating to a bare path. This occurs in production and was introduced in v16.2.0. The fix requires understanding the router's query parameter handling logic.

Issue Description

Link to the code that reproduces this issue

https://github.com/dlehmhus/next-router-replace-bug

To Reproduce

Build and start the application
Navigate to the home page with a query parameter, e.g. http://localhost:3000/?query=param
Click "Go to dummy page 1" — this navigates to /dummy-page-1 via
Click "Go to dummy page 2" — this navigates to /dummy-page-2 via
Click "Go to home" — this calls router.replace("/")

Current vs. Expected behavior

Following the steps above, I expected router.replace("/") to navigate to / with no query string. Instead, the browser navigates to /?query=param — the query parameters from the very first page load are re-appended to the replaced URL.

The bug occurs because router.replace("/") in the App Router appears to preserve (or restore) the query parameters that were present in the initial URL of the session, rather than replacing the full URL with the bare path provided.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:40 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6000
  Available memory (MB): 16384
  Available CPU cores: 10
Binaries:
  Node: 24.13.0
  npm: 11.6.2
  Yarn: 1.22.19
  pnpm: 8.15.9
Relevant Packages:
  next: 16.2.1-canary.1 // Latest available version is detected (16.2.1-canary.1).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Linking and Navigating

Which stage(s) are affected? (Select all that apply)

next start (local)

Additional context

This is just a production issue; dev works fine. The issue was introduced in v16.2.0.

GitHub Labels