What causes "Path is required" in mastra-ai/mastra?

Add the path query parameter to the request, URL-encoded (e.g. ?path=%2Fsrc%2Fmain.ts).

mastra-ai/mastra · error · HTTPException

Path is required

Error message

Path is required

What it means

Validation error thrown by the workspace file read handler (HTTP 400) when the request omits the required path parameter. The handler needs a path to locate the file within the workspace filesystem, so it rejects any request without one before doing any work.

Source

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

// Filesystem Routes
// =============================================================================

export const WORKSPACE_FS_READ_ROUTE = createRoute({
  method: 'GET',
  path: '/workspaces/:workspaceId/fs/read',
  responseType: 'json',
  pathParamSchema: workspaceIdPathParams,
  queryParamSchema: fsReadQuerySchema,
  responseSchema: fsReadResponseSchema,
  summary: 'Read file content',
  description: 'Returns the content of a file at the specified path',
  tags: ['Workspace'],
  handler: async ({ mastra, path, encoding, workspaceId }) => {
    try {
      requireWorkspaceV1Support();

      if (!path) {
        throw new HTTPException(400, { message: 'Path is required' });
      }

      const workspace = await getWorkspaceById(mastra, workspaceId);
      if (!workspace?.filesystem) {
        throw new HTTPException(404, { message: 'No workspace filesystem configured' });
      }

      const decodedPath = decodeURIComponent(path);

      // Check if path exists
      if (!(await workspace.filesystem.exists(decodedPath))) {
        throw new HTTPException(404, { message: `Path "${decodedPath}" not found` });
      }

      // Read file content
      const content = await workspace.filesystem.readFile(decodedPath, {
        encoding: (encoding as BufferEncoding) || 'utf-8',
      });

View on GitHub (pinned to 75dd419e61)

Solutions

Add the path query parameter to the request, URL-encoded (e.g. ?path=%2Fsrc%2Fmain.ts).
Check the client code that builds the URL to ensure the path variable is defined and non-empty.
For empty-string paths, resolve to a real relative path (like '.' for listing) instead of sending nothing.

Example fix

// before
fetch(`/api/workspaces/${id}/file`);
// after
fetch(`/api/workspaces/${id}/file?path=${encodeURIComponent('src/main.ts')}`);

Defensive patterns

Strategy: validation

Validate before calling

if (!path || typeof path !== 'string') {
  throw new Error('readFile requires a non-empty workspace-relative path');
}

Type guard

function hasPath(p: unknown): p is string {
  return typeof p === 'string' && p.length > 0;
}

Try / catch

try {
  return await readWorkspaceFile({ workspaceId, path });
} catch (e) {
  if (isHttpException(e, 400) && e.message === 'Path is required') {
    throw new Error(`Caller bug: path was not provided for workspace ${workspaceId}`);
  }
  throw e;
}

Prevention

Validate path inputs at the edge of your client code before building requests.
Always pass paths through encodeURIComponent exactly once.
Avoid interpolating possibly-undefined variables into query strings.

When it happens

Trigger: GET-ing the workspace file read route without the path query parameter (or with an empty string), e.g. a client bug that drops the query param after URL construction or an empty template variable.

Common situations: Template literal interpolation with an undefined path variable, URL builders that skip empty query params inconsistently, or manual curl testing that forgets ?path=.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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