{"record":{"id":"4600de2598452cf6","repo":"mastra-ai/mastra","slug":"invalid-route-path-path-path-cannot-contain","errorCode":null,"errorMessage":"Invalid route path: \"${path}\". Path cannot contain '..', '?', or '#'","messagePattern":"Invalid route path: \"(.+?)\"\\. Path cannot contain '\\.\\.', '\\?', or '#'","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"client-sdks/client-js/src/utils/index.ts","lineNumber":18,"sourceCode":"import { RequestContext } from '@mastra/core/request-context';\n\n/**\n * Normalizes a route path to ensure consistent formatting.\n * - Removes leading/trailing whitespace\n * - Validates no path traversal (..), query strings (?), or fragments (#)\n * - Collapses multiple consecutive slashes\n * - Removes trailing slashes\n * - Ensures leading slash (unless empty)\n *\n * @param path - The route path to normalize\n * @returns The normalized path (empty string for root paths)\n * @throws Error if path contains invalid characters\n */\nexport function normalizeRoutePath(path: string): string {\n  let normalized = path.trim();\n  if (normalized.includes('..') || normalized.includes('?') || normalized.includes('#')) {\n    throw new Error(`Invalid route path: \"${path}\". Path cannot contain '..', '?', or '#'`);\n  }\n  normalized = normalized.replace(/\\/+/g, '/');\n  if (normalized === '/' || normalized === '') {\n    return '';\n  }\n  if (normalized.endsWith('/')) {\n    normalized = normalized.slice(0, -1);\n  }\n  if (!normalized.startsWith('/')) {\n    normalized = `/${normalized}`;\n  }\n  return normalized;\n}\n\n/**\n * Checks if a value is a \"complex\" type that needs JSON serialization for query params.\n * Complex types: objects (excluding Date), arrays\n * Primitive types: string, number, boolean, null, undefined, Date","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/client-js/src/utils/index.ts#L1-L36","documentation":"normalizeRoutePath validates route path strings used to build client URLs and throws when the path contains '..', '?', or '#'. These characters either enable path traversal or are reserved for query/fragment semantics, so the client rejects them up front instead of producing a malformed or unsafe URL.","triggerScenarios":"Passing a path string containing '..' (traversal segments), '?' (query string), or '#' (fragment) to any client helper that routes through normalizeRoutePath — e.g. building resource URLs from user-supplied agent/workflow/thread names or path segments.","commonSituations":"Concatenating user input or identifiers that contain query strings into route paths, double-encoding URLs so '?' or '#' survive, or building paths like '/api/agents/' + name where name came from an untrusted source or an old config with '../../other' style overrides.","solutions":["Inspect the path value passed to the client and remove any '?query=...' or '#fragment' parts; pass query params via the client's options instead.","Sanitize identifiers used in paths (strip or encode '..', '?', '#') before constructing routes.","If traversal was intended, restructure the call to use the correct base path/resource rather than relative '..' segments.","Decode once and re-encode properly: use encodeURIComponent on dynamic segments so reserved chars never reach raw path form.","Check version-specific behavior: if a previously-working path now throws, a validation release tightened normalizeRoutePath."],"exampleFix":"// before\nclient.getAgent(`/api/agents/${name}?version=2`);\n// after\nclient.getAgent(`/api/agents/${encodeURIComponent(name)}`, { query: { version: 2 } });","handlingStrategy":"validation","validationCode":"function isValidRoutePath(path: string): boolean {\n  const p = path.trim();\n  return !p.includes('..') && !p.includes('?') && !p.includes('#');\n}\nif (!isValidRoutePath(userPath)) throw new Error('Rejected route path: ' + userPath);","typeGuard":null,"tryCatchPattern":"try {\n  normalizeRoutePath(userPath);\n} catch (e) {\n  if (e.message.startsWith('Invalid route path')) {\n    console.warn('Sanitizing path', userPath);\n    userPath = encodeURIComponent(userPath);\n  } else throw e;\n}","preventionTips":["Always encodeURIComponent dynamic path segments.","Pass query parameters via request options, never by appending '?' to paths.","Reject or sanitize '..' in any user-controlled identifiers before building routes.","Add a unit test that feeds suspect identifiers through route-building helpers."],"tags":["validation","url","security","path-traversal"],"backgroundTag":"invalid-route-path","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}