Array of string with empty query string and default [] is causing Uncaught Error: Maximum update depth exceeded.

[shrestha12344]

Context

What's your version of nuqs?

"nuqs": "^2.4.1",

What framework are you using?

• ✅Next.js (app router)

Which version of your framework are you using?

"next": "^14.1.0",
"react": "^18",

Description

Array of string with empty query string and default [] is causing Uncaught Error: Maximum update depth exceeded. I am using the state in useCallback dependency. It is working when I remove withDefault([]) but have to add || [] wherever I use the state as its value is null. It is also working when I append '?types=' to URL.

Reproduction

  const [types, setTypes] = useQueryState(
    "types",
    parseAsArrayOf(parseAsString).withDefault([])
  );

This will throw error with empty query in URL when we add that state in useCallback dependency.

[franky47]

The minimum version of Next.js supported is 14.2.0, early versions of Next.js 14 had issues with routing, prefetching etc (see #423 for reference).

Would you be able to update to 14.2.0 (or better, 14.2.26 which solves the CVE-2025-29927 middleware vulnerability), and see if you still encounter the issue?

[adriandmitroca]

I'm experiencing the same thing on Vite-based project with React Router v7, it doesn't seem to be Next related.

[franky47]

Ah I see, it's a referential equality problem. Your default empty array is not the same reference on every render, which causes instability of the value being returned if the URL is empty.

Try moving your parser definition outside the render body:

const parseAsTypes = parseAsArrayOf(parseAsString).withDefault([])

function useTypes() {
  return useQueryState("types", parseAsTypes);
}

[adriandmitroca]

Would using JSON.stringify for equality checks be a good approach to handle this within nuqs itself? I can see many React apps overlooking this issue since it’s easy to miss.

[franky47]

There is no equality check, the default value is returned as passed if the parsed state is null:

https://github.com/47ng/nuqs/blob/next/packages/nuqs/src/useQueryState.ts#L309

You could use this JSON.stringify trick further down in the dependency arrays that consume query states, but the better fix is to ensure stability at the source.

[adriandmitroca]

Ah right, makes perfect sense in such case.

[shrestha12344]

Its working after moving parser definition outside the component but I have to provide custom eq as below to remove query from URL when we have []. I have a custom parser using btoa and atob.

  eq(a, b) {
    return JSON.stringify(a) === JSON.stringify(b);
  }

[franky47]

That's the correct approach!

We had a suggestion for a base64 conversion utility (see #552), the issue of using atob/btoa is that they don't handle the extended Unicode charset.