mastra-ai/mastra · error · HTTPException

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

Error message

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

What it means

Thrown by assertSafeFilePath when a skill file path passed to the workspace skills mount endpoint is absolute (starts with '/' on POSIX or matches /^[a-zA-Z]:/ for drive letters on Windows). The server rejects absolute paths so a malicious or buggy API response cannot cause writes outside the target skill directory. It surfaces as an HTTPException with status 400.

Source

Thrown at packages/server/src/server/handlers/workspace.ts:1306

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

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.
 */
function assertSafeFilePath(filePath: string): string {
  // Reject absolute paths
  if (filePath.startsWith('/') || /^[a-zA-Z]:/.test(filePath)) {
    throw new HTTPException(400, {
      message: `Invalid file path "${filePath}". Absolute paths are not allowed.`,
    });
  }
  // Reject path traversal attempts
  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;
}

interface SkillFileEntry {
  path: string;
  content: string;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a path relative to the skill directory (e.g. 'SKILL.md' or 'scripts/run.sh') instead of an absolute path.
2. Strip leading slashes or drive prefixes before calling the endpoint, or normalize the path client-side.
3. Verify the path actually came from the Skills API response and was not user-controlled input pasted into the request.

Example fix

// before
await installSkill({ workspaceId, skillId, filePath: '/skills/foo/SKILL.md' });
// after
const relative = '/skills/foo/SKILL.md'.replace(/^([a-zA-Z]:)?[\\/]+/, '');
await installSkill({ workspaceId, skillId, filePath: relative });

function isRelativeSafePath(p) {
  return typeof p === 'string' && p.length > 0 && !p.startsWith('/') && !/^[a-zA-Z]:/.test(p);
}
if (!isRelativeSafePath(filePath)) throw new Error('Use a path relative to the skill directory');

function isSafeRelativePath(p: unknown): p is string {
  return typeof p === 'string' && !p.startsWith('/') && !/^[a-zA-Z]:/.test(p);
}

try {
  await installSkill({ workspaceId, filePath });
} catch (e) {
  if (String(e.message).includes('Absolute paths are not allowed')) {
    filePath = filePath.replace(/^([a-zA-Z]:)?[\\/]+/, '');
    await installSkill({ workspaceId, filePath });
  } else throw e;
}

When it happens

Trigger: Calling the workspace install-skill/mount-skill endpoint with a file path like '/etc/passwd', 'C:\evil\file', or forwarding an unvalidated path field from a third-party skills API response into assertSafeFilePath.

Common situations: Proxies that pass client-supplied paths straight through; upstream skills registries returning absolute or Windows-style paths; tests or scripts hardcoding absolute local paths when calling the API.

Related errors

• Invalid file path "${filePath}". Path traversal is not allow
• Invalid file path "${filePath}". Absolute paths are not allo
• Invalid file path "${filePath}". Path traversal is not allow
• Path is required
• Path and content are required

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