vercel/next.js · error · ReadonlyURLSearchParamsError

Method unavailable on `ReadonlyURLSearchParams`. Read more…

Error message

Method unavailable on `ReadonlyURLSearchParams`. Read more: https://nextjs.org/docs/app/api-reference/functions/use-search-params#updating-searchparams

What it means

Mutation guard on ReadonlyURLSearchParams: a mutating URLSearchParams method such as append was called on the object returned by useSearchParams. The wrapper class throws ReadonlyURLSearchParamsError from every mutator because search params are owned by the router and must be updated via navigation, not in place.

Solutions

1. Do not mutate ReadonlyURLSearchParams; build a new URLSearchParams from useSearchParams() and navigate with router.push/replace instead.

When it happens

Trigger: A mutating method is called on the read-only URLSearchParams from useSearchParams.

Common situations: Calling set/append/delete on the search params object returned by useSearchParams instead of using the router.

AI-assisted analysis of vercel/next.js@0eb3775416 (2026-08-19). Data as JSON: /api/errors/3a5d6291fb25c165. Report an issue: GitHub.

Appendix: source

Thrown at packages/next/src/client/components/readonly-url-search-params.ts:23

 */

/** @internal */
class ReadonlyURLSearchParamsError extends Error {
  constructor() {
    super(
      'Method unavailable on `ReadonlyURLSearchParams`. Read more: https://nextjs.org/docs/app/api-reference/functions/use-search-params#updating-searchparams'
    )
  }
}

/**
 * A read-only version of URLSearchParams that throws errors when mutation methods are called.
 * This ensures that the URLSearchParams returned by useSearchParams() cannot be mutated.
 */
export class ReadonlyURLSearchParams extends URLSearchParams {
  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. Read more: https://nextjs.org/docs/app/api-reference/functions/use-search-params#updating-searchparams */
  append() {
    throw new ReadonlyURLSearchParamsError()
  }
  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. Read more: https://nextjs.org/docs/app/api-reference/functions/use-search-params#updating-searchparams */
  delete() {
    throw new ReadonlyURLSearchParamsError()
  }
  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. Read more: https://nextjs.org/docs/app/api-reference/functions/use-search-params#updating-searchparams */
  set() {
    throw new ReadonlyURLSearchParamsError()
  }
  /** @deprecated Method unavailable on `ReadonlyURLSearchParams`. Read more: https://nextjs.org/docs/app/api-reference/functions/use-search-params#updating-searchparams */
  sort() {
    throw new ReadonlyURLSearchParamsError()
  }
}

View on GitHub (pinned to 0eb3775416)