mastra-ai/mastra · warning · HTTPException

Invalid file path "${filePath}". Absolute paths are not allo

Error message

Invalid file path "${filePath}". Absolute paths are not allowed.

What it means

A 400 security validation from `assertSafeFilePath`, rejecting any file path that is absolute: starts with '/' or '\\', or matches a Windows drive pattern like 'C:\\'. It prevents malicious upstream skill responses from writing outside the skill directory.

Source

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

const SKILL_NAME_REGEX = /^[a-z0-9][a-z0-9-_]*$/i;

export function assertSafeSkillName(name: string): string {
  if (!SKILL_NAME_REGEX.test(name)) {
    throw new HTTPException(400, {
      message: `Invalid skill name "${name}". Names must start with alphanumeric and contain only letters, numbers, hyphens, and underscores.`,
    });
  }
  return name;
}

/**
 * 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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Convert paths to relative form before sending: strip the leading '/' or drive prefix.
2. Reject or skip skills whose manifests contain absolute paths; report the skill as unsafe.
3. Compute relative paths with path.relative(baseDir, absolutePath) and verify the result doesn't escape the base.
4. Only install skills from trusted sources.

Example fix

// before
const filePath = '/src/agent.ts';
await installSkillFile(skill, filePath);
// after
const filePath = '/src/agent.ts'.replace(/^([a-zA-Z]:)?[\\/]+/, '');
await installSkillFile(skill, filePath); // "src/agent.ts"

if (/^([a-zA-Z]:)?[\\/]/.test(filePath)) throw new Error(`Path "${filePath}" must be relative to the skill directory.`);

try {
  await installSkill(skill);
} catch (e) {
  if (e instanceof MastraClientError && e.status === 400 && /Absolute paths are not allowed/.test(e.message)) {
    console.error('Skill manifest contains an absolute path — treat the skill as untrusted and skip or report it.');
  } else throw e;
}

When it happens

Trigger: Installing/downloading a skill whose manifest lists files with absolute paths (e.g. '/etc/passwd' or 'C:\\Windows\\x'), or constructing a file path yourself using an absolute base directory.

Common situations: A third-party skill in the registry publishes malicious absolute paths; joining an absolute base dir with a path that already starts with '/'; Windows-style paths pasted from another machine.

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}". Path traversal is not allow
• 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/4909297806a624ce. Report an issue: GitHub.