What causes "Path and content are required" in mastra-ai/mastra?

Send both the path parameter (URL-encoded) and a non-undefined content body.

mastra-ai/mastra · error · HTTPException

Path and content are required

Error message

Path and content are required

What it means

Validation error (HTTP 400) thrown by the workspace file write handler when either the path parameter or the content body is missing. Both are required to create/update a file, so the handler rejects the request up front before touching the filesystem.

Source

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

  },
});

export const WORKSPACE_FS_WRITE_ROUTE = createRoute({
  method: 'POST',
  path: '/workspaces/:workspaceId/fs/write',
  responseType: 'json',
  pathParamSchema: workspaceIdPathParams,
  bodySchema: fsWriteBodySchema,
  responseSchema: fsWriteResponseSchema,
  summary: 'Write file content',
  description: 'Writes content to a file at the specified path. Supports base64 encoding for binary files.',
  tags: ['Workspace'],
  handler: async ({ mastra, path, content, encoding, recursive, workspaceId }) => {
    try {
      requireWorkspaceV1Support();

      if (!path || content === undefined) {
        throw new HTTPException(400, { message: 'Path and content are required' });
      }

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

      if (workspace.filesystem?.readOnly) {
        throw new HTTPException(403, { message: 'Workspace is in read-only mode' });
      }

      const decodedPath = decodeURIComponent(path);

      // Handle base64-encoded content for binary files
      let fileContent: string | Buffer = content;
      if (encoding === 'base64') {
        fileContent = Buffer.from(content, 'base64');
      }

View on GitHub (pinned to 75dd419e61)

Solutions

Send both the path parameter (URL-encoded) and a non-undefined content body.
Inspect the request layer for undefined fields being dropped; use null-checked defaults before sending.
For intentionally empty files, send an empty string '' as content — only undefined/missing triggers the error.

Example fix

// before
await client.write(path); // content undefined
// after
await client.write(path, ''); // or the actual file content

Defensive patterns

Strategy: validation

Validate before calling

if (typeof path !== 'string' || path.length === 0 || content === undefined) {
  throw new Error('writeFile requires a non-empty path and defined content (use "" for an empty file)');
}

Type guard

function canWrite(path: unknown, content: unknown): path is string {
  return typeof path === 'string' && path.length > 0 && content !== undefined;
}

Try / catch

try {
  await writeWorkspaceFile({ workspaceId, path, content });
} catch (e) {
  if (isHttpException(e, 400) && e.message.includes('Path and content are required')) {
    throw new Error(`Write aborted: path=${JSON.stringify(path)} content=${typeof content} — check request serialization`);
  }
  throw e;
}

Prevention

Never rely on JSON.stringify to carry undefined content — it drops the field.
Use explicit empty strings for intentionally empty files.
Validate path/content at the client boundary before each write.

When it happens

Trigger: POST/PUT to the workspace file write route with no path query parameter, no request body, an empty-string path, or content explicitly undefined — commonly from a misconfigured HTTP client or a serialization step that drops falsy fields.

Common situations: JSON.stringify stripping undefined content fields; a form/pipeline step that yields an empty path variable; clients sending form data where the server expects raw string content.

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/ae28a3241b4a8557. Report an issue: GitHub.