You haven't wrapped the components calling useQueryState(s) with
an adapter.
Adapters are based on React Context, and provide nuqs hooks with the interfaces to work with your framework: reacting to URL changes, and calling your router when you update your state.
Follow the setup instructions to import and wrap your application using a suitable adapter:
- Next.js (app router)
- Next.js (pages router)
- React SPA (eg: with Vite)
- Remix
- React Router v6
- React Router v7
If you encounter this error outside of the browser, like in a test
runner (eg: Vitest or Jest), you may use the testing adapter
from nuqs/adapters/testing to mock the initial search params and access
setup/assertion testing facilities.
This error can also occur in monorepo setups where components using nuqs hooks
are in different packages resolving to different nuqs versions,
leading to different context references being used.
If you enable debugging, you might see a
NUQS-303 - Multiple adapter contexts detected error, confirming
this hypothesis.
For additional clarification, ensure that all packages use compatible versions
of nuqs to prevent this issue from arising. See issue
#798 for more details and
possible solutions.