mastra-ai/mastra · error · Error

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

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.

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)

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

• Invalid route path: "${path}". Path cannot contain '..', '?'
• Worker ${label} must stay within the deployed artifact root.
• ${label} must be relative
• ${label} escapes workspace
• Path escapes workspace

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