mastra-ai/mastra · warning · HTTPException

Invalid file path "${filePath}". Path traversal is not allow

Error message

Invalid file path "${filePath}". Path traversal is not allowed.

What it means

A 400 from `assertSafeFilePath` raised when any path segment equals '..' or '.', i.e. the path attempts directory traversal. Backslashes are normalized first so Windows-style traversal ("..\\..\\etc\\passwd") is caught too. This guards the skill directory sandbox.

Source

Thrown at packages/server/src/server/handlers/skills-sh-shared.ts:114

}

/**
 * Validate that a file path is safe (no traversal, no absolute paths).
 * Prevents malicious API responses from writing files outside the skill
 * directory.
 */
export function assertSafeFilePath(filePath: string): string {
  if (filePath.startsWith('/') || filePath.startsWith('\\') || /^[a-zA-Z]:[\\/]/.test(filePath)) {
    throw new HTTPException(400, {
      message: `Invalid file path "${filePath}". Absolute paths are not allowed.`,
    });
  }
  // Normalize backslashes to forward slashes so Windows-style traversal
  // (e.g. "..\\..\\etc\\passwd") cannot bypass the segment check below.
  const segments = filePath.split(/[\\/]/);
  for (const segment of segments) {
    if (segment === '..' || segment === '.') {
      throw new HTTPException(400, {
        message: `Invalid file path "${filePath}". Path traversal is not allowed.`,
      });
    }
  }
  return filePath;
}

// =============================================================================
// API calls
// =============================================================================

interface UpstreamSkillsList {
  skills: Array<{
    skillId: string;
    name: string;
    installs: number;
    source: string;
    owner: string;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Remove '..' and '.' segments by resolving the path within the skill directory and re-relativizing it.
2. Skip/flag the offending file or skill rather than rewriting it blindly.
3. Use path.posix.normalize and verify the result stays inside the skill root before persisting.
4. Validate paths client-side with the same segment check before calling the API.

Example fix

// before
const filePath = '../../etc/passwd';
await installSkillFile(skill, filePath);
// after
const safe = filePath.split(/[\\/]/).every(s => s !== '..' && s !== '.');
if (!safe) throw new Error('Refusing unsafe path');
await installSkillFile(skill, filePath);

const segments = filePath.split(/[\\/]/);
if (segments.some(s => s === '..' || s === '.')) throw new Error(`Path "${filePath}" contains traversal segments.`);

try {
  await installSkill(skill);
} catch (e) {
  if (e instanceof MastraClientError && e.status === 400 && /Path traversal is not allowed/.test(e.message)) {
    console.error('Skill file path attempts traversal — reject the file/skill as unsafe.');
  } else throw e;
}

When it happens

Trigger: A skill file entry like '../../escape.txt' or '.\\..\\secret'; any relative path containing dot-dot segments submitted to skill file operations.

Common situations: Malicious or buggy upstream skill manifests using '..' to escape the skill directory; generating relative paths with string concatenation instead of path libraries.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• Invalid file path "${filePath}". Absolute paths are not allo
• Path traversal detected: skill name "${skillName}" escapes s
• Path traversal detected: "${relativePath}" escapes skill dir
• Invalid ${label} path: ${input}
• Invalid file path "${filePath}". Path traversal is not allow

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