nuqs state not updating correctly when using Next.js `cacheComponents=true`

[franky47]

Discussed in #1272

^{Originally posted by rajput-hemant December 22, 2025}
Hi 👋
I’m running into an issue with nuqs where the URL state seems to stay stale when cacheComponents: true is enabled in next.config.js.

Context

I have a task list → task edit flow where:

• The selected taskId is stored in the URL using nuqs
• When clicking Edit, I navigate to a task form page
• The form is prefilled based on the taskId from nuqs state

This works fine until a previously edited task is deleted.

Problem

When cacheComponents: true is enabled:

• nuqs continues to return the previous taskId
• Even after navigating back to the list and selecting a different task
• This causes the app to try fetching a deleted task, resulting in an error

This behavior does not occur when cacheComponents is disabled.

I’m not sure if this is:

• A bug in nuqs
• An interaction issue with Next.js component caching
• Or expected behavior, and I need to explicitly opt out of caching nuqs state

---

Expected behavior

• nuqs state should reflect the latest URL param
• When navigating back and selecting a new task, the old taskId should not be reused
• Deleting a task should not cause stale URL state to persist

---

Actual behavior

• nuqs returns a stale taskId
• App attempts to fetch a task that no longer exists
• This only happens when cacheComponents: true is enabled

---

Steps to reproduce

1. Enable cacheComponents: true in next.config.js

2. Open the task list page

3. Click Edit on Task A

   • You are navigated to the edit form
   • Form is prefilled correctly
   • nuqs state contains taskId = A

4. Navigate back to the task list

5. Delete Task A

6. Click Edit on Task B

7. ❌ App still reads taskId = A from nuqs

8. ❌ Fetch fails because Task A no longer exists

---

Reproduction sandbox

I’ve created a minimal CodeSandbox with everything needed to reproduce the issue:

👉 https://codesandbox.io/p/devbox/32lkt4

---

Questions

1. Is this behavior expected when using cacheComponents: true?

2. If yes, what’s the recommended way to:

   • Opt out of this caching for nuqs state?
   • Or force nuqs to always sync with the latest URL params?

3. If not expected, I’m happy to raise an issue.

Thanks in advance 🙏
Appreciate all the work on nuqs — it’s been great otherwise!

Screen.Recording.2025-12-22.at.9.43.34.PM.mov

[franky47]

Thanks for the report, I can reproduce it locally.

The issue seems to be that, for some reason, when navigating back the useQueryState hook is still rendering in the /task page in the background, with the previous value of the taskId. You can see this by enabling the nuqs debug logs (localStorage.debug = 'nuqs' in your devtools and reloading the page).

I wonder if it's related to #1156. I'll try and make a minimal repro I can run tests against.

[AyushNigam-1]

Hi! I’ve opened a PR that addresses this issue by removing render-time dependency on searchParams and syncing query state reactively to handle App Router cached components correctly.

The fix is scoped to this behavior, doesn’t change the public API, and resolves the repro described here.
I’d really appreciate it if you could take a look and share any feedback. Thanks!

[franky47]

@AyushNigam-1 have you run the tests to confirm it works?

If you look at issue #1156, there is a proposed preview build that fixes it and may be relevant here too.

[AyushNigam-1]

After testing the preview build from #1320, it does appear to resolve the repro from #1272 on my end.
Thanks for pointing that out , happy to close my PR or rework it as a follow-up if needed.

[franky47]

Unfortunately the fix in #1320 (shipped in v2.8.8) doesn't solve the repro for this / #1272, there is still a cached state value that triggers the error.

[AyushNigam-1]

I went back and double-checked this more carefully, and you’re right , the fix in #1320 does not fully resolve the repro in #1272. My earlier conclusion was based on an incomplete check on my side, so apologies for the confusion there.

For my latest attempt at addressing this issue, I’ve been thinking about how to best cover it with a regression test, but I’m not fully confident about what the right invariant should be here, especially given App Router semantics and the limitations of our test adapters.

Before pushing anything, I wanted to ask for your guidance:
would you expect a test here to explicitly guard against reading URL state during render, or is it sufficient to assert the observable behavior after mount/effects have run?

I’d really appreciate your input on what kind of test you think would be most appropriate for this case before I add one.

[franky47]

I added a test configuration with cacheComponents in #1324, which surprisingly passed with all the e2e test suite (aside from locators duplication due to the Activity behaviour of having both pages in the DOM during navigation).

I need to read into vercel/next.js#86577 a bit more to try and understand the Activity behaviour, which could explain this issue, in order to add a minimal e2e test case to repro the issue here and that fails in the cacheComponents test configuration.

[AyushNigam-1]

Thanks for looking into this and for adding the cacheComponents test setup .

Happy to follow along and help further once there’s more clarity on a test strategy 👍

[franky47]

I have a working reproduction in #1334, that only fails in app router + cacheComponents.

The issue is indeed related to <Activity> keeping the destination page (/app/repro-1273/other in the test, and the task form page in the OG issue) in the DOM when we both navigate back to the home page and causes a render with that stale state when mounting the new destination page before becoming eventually consistant with what's in the URL.