mastra-ai/mastra · error · Error

Invalid route path: " ". Path cannot contain '..', '?', or…

Error message

Invalid route path: "${path}". Path cannot contain '..', '?', or '#'

What it means

normalizeRoutePath validates and canonicalizes route paths, collapsing duplicate slashes and normalizing the root path. Paths containing '..', '?', or '#' are rejected outright because they enable path traversal or are not valid route path components. The original (not trimmed) path is included in the error message.

Solutions

1. Remove '?...' query strings from the path and accept query params via the request handler instead
2. Remove any '#...' fragment from the path — fragments are client-side only and never part of a route
3. Resolve '..' segments statically (use absolute, literal paths like '/api/agents')
4. Sanitize any dynamic input before interpolating it into route paths

Example fix

// before
registerApiRoute(`/api/agents?version=${v}`, handler)
// after
registerApiRoute('/api/agents', handler) // pass ?version= in the actual request query

if (/[?#]/.test(routePath) || routePath.includes('..')) {
  throw new Error('Rejecting unsafe route path');
}

const safePath = (p: unknown): p is string =>
  typeof p === 'string' && !p.includes('..') && !/[?#]/.test(p);

When it happens

Trigger: Passing a route path containing '..' (traversal), a query string ('?'), or a fragment ('#') to normalizeRoutePath, which is invoked when registering API routes or building server route tables.

Common situations: Accidentally concatenating a query string into a route path (e.g. '/agents?id=1' instead of passing query params separately); building paths from user input or template strings that include '..'; copy-pasting URLs (with fragments) into route definitions.

Related errors

• configDirName must be a single directory name without path…
• [FilesystemStorage] path must be a non-empty relative path.
• Invalid checkpoint name
• Invalid path
• Invalid mount path: . Path segments cannot be "." or "..".

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/4772323edb1c3431. Report an issue: GitHub.

Appendix: source

Thrown at packages/server/src/server/utils.ts:39

  return standardSchemaToJSONSchema(standardSchema);
}

/**
 * Normalizes a route path to ensure consistent formatting.
 * - Removes leading/trailing whitespace
 * - Validates no path traversal (..), query strings (?), or fragments (#)
 * - Collapses multiple consecutive slashes
 * - Removes trailing slashes
 * - Ensures leading slash (unless empty)
 *
 * @param path - The route path to normalize
 * @returns The normalized path (empty string for root paths)
 * @throws Error if path contains invalid characters
 */
export function normalizeRoutePath(path: string): string {
  let normalized = path.trim();
  if (normalized.includes('..') || normalized.includes('?') || normalized.includes('#')) {
    throw new Error(`Invalid route path: "${path}". Path cannot contain '..', '?', or '#'`);
  }
  normalized = normalized.replace(/\/+/g, '/');
  if (normalized === '/' || normalized === '') {
    return '';
  }
  if (normalized.endsWith('/')) {
    normalized = normalized.slice(0, -1);
  }
  if (!normalized.startsWith('/')) {
    normalized = `/${normalized}`;
  }
  return normalized;
}

const DEFAULT_STORED_RESOURCE_SCOPE_METADATA_KEY = 'mastra.resourceId';

export type StoredResourceScope = {
  metadataKey: string;

View on GitHub (pinned to 75dd419e61)