{"record":{"id":"bc316d32fe9d3570","repo":"vercel/next.js","slug":"failed-to-decode-path-param-s","errorCode":null,"errorMessage":"Failed to decode path param(s).","messagePattern":"Failed to decode path param\\(s\\)\\.","errorType":"exception","errorClass":"DecodeError","httpStatus":null,"severity":"error","filePath":"packages/next/src/server/lib/router-utils/decode-path-params.ts","lineNumber":21,"sourceCode":"\n/**\n * We only encode path delimiters for path segments from\n * getStaticPaths so we need to attempt decoding the URL\n * to match against and only escape the path delimiters\n * this allows non-ascii values to be handled e.g.\n * Japanese characters.\n * */\nfunction decodePathParams(pathname: string): string {\n  // TODO: investigate adding this handling for non-SSG\n  // pages so non-ascii names also work there.\n  return pathname\n    .split('/')\n    .map((seg) => {\n      try {\n        seg = escapePathDelimiters(decodeURIComponent(seg), true)\n      } catch (_) {\n        // An improperly encoded URL was provided\n        throw new DecodeError('Failed to decode path param(s).')\n      }\n      return seg\n    })\n    .join('/')\n}\n\nexport { decodePathParams }\n","sourceCodeStart":3,"sourceCodeEnd":29,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/server/lib/router-utils/decode-path-params.ts#L3-L29","documentation":"Thrown by decodePathParams (as a DecodeError) when a path segment contains malformed percent-encoding that decodeURIComponent cannot parse (e.g. '%zz' or a lone '%' at the end). Next.js decodes URL path params to match dynamic routes, and invalid escapes make decoding impossible.","triggerScenarios":"A request URL contains a path segment with an invalid percent-escape sequence, such as /post/%zz or /user/100%. decodeURIComponent throws URIError which is rethrown as DecodeError.","commonSituations":"Clients sending unencoded special characters, a reverse proxy double-decoding/encoding, or a misconfigured redirect that mangles the path. Bots/scanners hitting odd URLs also trigger this.","solutions":["Ensure the client sends properly percent-encoded URLs (e.g. %20 for space, %25 for a literal %).","If a proxy is double-encoding, fix the proxy to pass the raw path through.","Add a rewrite or middleware to sanitize/normalize incoming paths before they reach the router.","For genuinely malformed requests, expect a 400 and ensure your error page handles it gracefully."],"exampleFix":"// before: client sends a raw percent\n// GET /files/report%.pdf  -> throws DecodeError\n\n// after: client encodes the percent\n// GET /files/report%25.pdf","handlingStrategy":"try-catch","validationCode":"function isDecodablePath(pathname: string): boolean {\n  return pathname.split('/').every(seg => {\n    try { decodeURIComponent(seg); return true } catch { return false }\n  })\n}","typeGuard":"function isDecodablePath(pathname: string): boolean {\n  try { decodeURIComponent(pathname); return true } catch { return false }\n}","tryCatchPattern":"try {\n  decodePathParams(pathname)\n} catch (e) {\n  if (e instanceof DecodeError) return new Response('Bad Request', { status: 400 })\n  throw e\n}","preventionTips":["Always percent-encode special characters in generated URLs.","Normalize/validate paths in middleware before they reach the router.","Watch for proxies that double-encode paths."],"tags":["routing","url-encoding","path-params"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}