vercel/next.js · error · DecodeError

failed to decode param

Error message

failed to decode param

What it means

getRouteMatcher's internal decode helper wraps decodeURIComponent for each matched dynamic parameter; when a captured URL segment contains a malformed percent-encoding (e.g. a truncated escape like '%E0%A4' or a stray '%'), decodeURIComponent throws and this DecodeError is raised instead of returning params, aborting route matching.

Solutions

1. Ensure dynamic route params are valid URI-encoded values.

When it happens

Trigger: Decoding a route parameter fails.

Common situations: A URL segment contains malformed percent-encoding that decodeURIComponent rejects.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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

Appendix: source

Thrown at packages/next/src/shared/lib/router/utils/route-matcher.ts:29

  // We only use the exec method of the RegExp object. This helps us avoid using
  // type assertions that the passed in properties are of the correct type.
  re: Pick<RegExp, 'exec'>
  groups: Record<string, Group>
}

export function getRouteMatcher({
  re,
  groups,
}: RouteMatcherOptions): RouteMatchFn {
  const rawMatcher = (pathname: string) => {
    const routeMatch = re.exec(pathname)
    if (!routeMatch) return false

    const decode = (param: string) => {
      try {
        return decodeURIComponent(param)
      } catch {
        throw new DecodeError('failed to decode param')
      }
    }

    const params: Params = {}
    for (const [key, group] of Object.entries(groups)) {
      const match = routeMatch[group.pos]
      if (match !== undefined) {
        if (group.repeat) {
          params[key] = match.split('/').map((entry) => decode(entry))
        } else {
          params[key] = decode(match)
        }
      }
    }

    return params
  }

View on GitHub (pinned to 0eb3775416)