{"record":{"id":"30dbb0e1bdc6caa9","repo":"mastra-ai/mastra","slug":"read-only-30dbb0","errorCode":"READ_ONLY","errorMessage":"Workspace is in read-only mode. Cannot perform: edit_file","messagePattern":"Workspace is in read-only mode\\. Cannot perform: edit_file","errorType":"error_code","errorClass":"WorkspaceReadOnlyError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/tools/edit-file.ts","lineNumber":62,"sourceCode":"      .boolean()\n      .optional()\n      .default(false)\n      .describe('If true, replace all occurrences. If false (default), old_string must be unique.'),\n  }),\n  execute: async ({ path, old_string, new_string, replace_all }, context) => {\n    const { workspace, filesystem } = requireFilesystem(context);\n    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE);\n\n    const span = startWorkspaceSpan(context, workspace, {\n      category: 'filesystem',\n      operation: 'editFile',\n      input: { path, replace_all },\n      attributes: { filesystemProvider: filesystem.provider },\n    });\n\n    try {\n      if (filesystem.readOnly) {\n        throw new WorkspaceReadOnlyError('edit_file');\n      }\n\n      const content = await filesystem.readFile(path, { encoding: 'utf-8' });\n\n      if (typeof content !== 'string') {\n        span.end({ success: false });\n        return `Cannot edit binary files. Use the write file tool instead.`;\n      }\n\n      const shouldReplaceAll = replace_all ?? false;\n      const lineRanges = getEditedLineRanges(content, old_string, new_string, shouldReplaceAll);\n      const result = replaceString(content, old_string, new_string, shouldReplaceAll);\n      await filesystem.writeFile(path, result.content, {\n        overwrite: true,\n        expectedMtime: (context as any)?.__expectedMtime,\n      });\n\n      let output = `Replaced ${result.replacements} occurrence${result.replacements !== 1 ? 's' : ''} in ${path}${lineRanges}`;","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/tools/edit-file.ts#L44-L80","documentation":"Thrown by the edit-file workspace tool when the filesystem is read-only. Editing a file (read + replace) mutates the workspace, so the tool throws WorkspaceReadOnlyError with code READ_ONLY before reading the file.","triggerScenarios":"Invoking the edit_file tool (path, search/replace, replace_all) against a workspace with filesystem.readOnly = true.","commonSituations":"Coding agents connected to read-only checkouts or production mounts; misconfigured deployment where the workspace volume is mounted ro.","solutions":["Enable write access on the workspace filesystem provider","Copy the project to a writable location and point the workspace there","Remount the volume read-write if the readOnly flag comes from an underlying mount","Catch READ_ONLY and instruct the user/agent that edits are unavailable in this environment"],"exampleFix":"// before\nnew Workspace({ filesystem: getReadOnlyFs() })\n// after\nnew Workspace({ filesystem: getWritableFs(rootDir) })","handlingStrategy":"validation","validationCode":"if (workspace.filesystem.readOnly) {\n  throw new Error('edit_file unavailable: workspace is read-only');\n}","typeGuard":"function canEdit(fs: WorkspaceFilesystem | undefined): fs is WorkspaceFilesystem & { readOnly: false } {\n  return !!fs && fs.readOnly === false;\n}","tryCatchPattern":"try {\n  await editTool.execute({ context: { path, ... }, ... });\n} catch (e: any) {\n  if (e?.code === 'READ_ONLY') {\n    return { error: 'Cannot edit files in a read-only workspace.' };\n  }\n  throw e;\n}","preventionTips":["Register edit tools only when filesystem is writable","Use writable dev clones for code-modifying agents","Check readOnly in pre-flight before agent runs","Remount volumes rw when the environment requires edits"],"tags":["read-only","workspace","edit-file","filesystem"],"backgroundTag":"workspace-read-only","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}