mastra-ai/mastra · error · WorkspaceReadOnlyError

READ_ONLY

READ_ONLY

Error message

Workspace is in read-only mode. Cannot perform: mkdir

What it means

The workspace filesystem was opened in read-only mode, and the `mkdir` tool refuses any mutating operation. Before executing, the tool checks `filesystem.readOnly` and throws `WorkspaceReadOnlyError('mkdir')`. This prevents writes on workspaces configured as inspection-only (e.g. mounted prod data).

Source

Thrown at packages/core/src/workspace/tools/mkdir.ts:33

      .boolean()
      .optional()
      .default(true)
      .describe('Whether to create parent directories if they do not exist'),
  }),
  execute: async ({ path, recursive }, context) => {
    const { workspace, filesystem } = requireFilesystem(context);
    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.MKDIR);

    const span = startWorkspaceSpan(context, workspace, {
      category: 'filesystem',
      operation: 'mkdir',
      input: { path, recursive },
      attributes: { filesystemProvider: filesystem.provider },
    });

    try {
      if (filesystem.readOnly) {
        throw new WorkspaceReadOnlyError('mkdir');
      }

      await filesystem.mkdir(path, { recursive });
      span.end({ success: true });
      return `Created directory ${path}`;
    } catch (err) {
      span.error(err);
      throw err;
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

1. If writes are intended, construct the filesystem/Workspace with read-only disabled
2. If read-only is intended, remove `mkdir` (and other write tools) from the tools config so the agent never attempts it
3. Handle the READ_ONLY error in the agent/tool layer and instruct the model the workspace is read-only

Example fix

// before
const ws = new Workspace({ filesystem: new LocalFilesystem(dir, { readOnly: true }) });
// mkdir tool enabled -> READ_ONLY error

// after
const ws = new Workspace({ filesystem: new LocalFilesystem(dir) }); // writable
// or: exclude write tools from tools config for read-only workspaces

if (filesystem.readOnly) {
  throw new Error('Workspace is read-only; remove mkdir/write tools from the tools config.');
}

try {
  await mkdirTool.execute({ path }, ctx);
} catch (err) {
  if (err?.code === 'READ_ONLY') {
    return { error: 'Workspace is read-only; changes must be applied externally.' };
  }
  throw err;
}

When it happens

Trigger: Calling the `mkdir` workspace tool while `filesystem.readOnly === true` — i.e. the Workspace/filesystem was constructed with a read-only flag or a read-only filesystem provider.

Common situations: Attaching agent tools to a read-only mounted workspace (shared/prod directories); a default config enabling all filesystem tools including mutators; forgetting to disable write tools when the workspace is read-only.

Related errors

• EACCES
• READ_ONLY
• READ_ONLY
• READ_ONLY
• READ_ONLY

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