{"record":{"id":"5d5bbe0e8d78d80c","repo":"mastra-ai/mastra","slug":"read-only-5d5bbe","errorCode":"READ_ONLY","errorMessage":"Workspace is in read-only mode. Cannot perform: mkdir","messagePattern":"Workspace is in read-only mode\\. Cannot perform: mkdir","errorType":"error_code","errorClass":"WorkspaceReadOnlyError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/tools/mkdir.ts","lineNumber":33,"sourceCode":"      .boolean()\n      .optional()\n      .default(true)\n      .describe('Whether to create parent directories if they do not exist'),\n  }),\n  execute: async ({ path, recursive }, context) => {\n    const { workspace, filesystem } = requireFilesystem(context);\n    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.MKDIR);\n\n    const span = startWorkspaceSpan(context, workspace, {\n      category: 'filesystem',\n      operation: 'mkdir',\n      input: { path, recursive },\n      attributes: { filesystemProvider: filesystem.provider },\n    });\n\n    try {\n      if (filesystem.readOnly) {\n        throw new WorkspaceReadOnlyError('mkdir');\n      }\n\n      await filesystem.mkdir(path, { recursive });\n      span.end({ success: true });\n      return `Created directory ${path}`;\n    } catch (err) {\n      span.error(err);\n      throw err;\n    }\n  },\n});\n","sourceCodeStart":15,"sourceCodeEnd":45,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/tools/mkdir.ts#L15-L45","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["If writes are intended, construct the filesystem/Workspace with read-only disabled","If read-only is intended, remove `mkdir` (and other write tools) from the tools config so the agent never attempts it","Handle the READ_ONLY error in the agent/tool layer and instruct the model the workspace is read-only"],"exampleFix":"// before\nconst ws = new Workspace({ filesystem: new LocalFilesystem(dir, { readOnly: true }) });\n// mkdir tool enabled -> READ_ONLY error\n\n// after\nconst ws = new Workspace({ filesystem: new LocalFilesystem(dir) }); // writable\n// or: exclude write tools from tools config for read-only workspaces","handlingStrategy":"validation","validationCode":"if (filesystem.readOnly) {\n  throw new Error('Workspace is read-only; remove mkdir/write tools from the tools config.');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await mkdirTool.execute({ path }, ctx);\n} catch (err) {\n  if (err?.code === 'READ_ONLY') {\n    return { error: 'Workspace is read-only; changes must be applied externally.' };\n  }\n  throw err;\n}","preventionTips":["When constructing a read-only workspace, also filter the tools config to read-only tools","Mirror readOnly state in the agent's system prompt so the model doesn't attempt writes","Add a unit test asserting mutating tools are absent for read-only workspace configs"],"tags":["read-only","filesystem","workspace","permissions"],"backgroundTag":"read-only-filesystem","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}