{"record":{"id":"1815df627e3c283f","repo":"mastra-ai/mastra","slug":"read-only-1815df","errorCode":"READ_ONLY","errorMessage":"Workspace is in read-only mode. Cannot perform: ast_edit","messagePattern":"Workspace is in read-only mode\\. Cannot perform: ast_edit","errorType":"error_code","errorClass":"WorkspaceReadOnlyError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/tools/ast-edit.ts","lineNumber":448,"sourceCode":"        isDefault: z.boolean().optional().describe('Whether the first name is a default import'),\n      })\n      .optional()\n      .describe('Required for add-import transform. Specifies the module and names to import.'),\n  }),\n  execute: async ({ path, pattern, replacement, transform, targetName, newName, importSpec }, context) => {\n    const { workspace, filesystem } = requireFilesystem(context);\n    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.AST_EDIT);\n\n    const span = startWorkspaceSpan(context, workspace, {\n      category: 'filesystem',\n      operation: 'astEdit',\n      input: { path, transform, pattern },\n      attributes: { filesystemProvider: filesystem.provider },\n    });\n\n    try {\n      if (filesystem.readOnly) {\n        throw new WorkspaceReadOnlyError('ast_edit');\n      }\n\n      // Load ast-grep (cached after first call)\n      const astGrep = await loadAstGrep();\n      if (!astGrep) {\n        span.end({ success: false });\n        return '@ast-grep/napi is not available. Install it to use AST editing.';\n      }\n      const { parse, Lang } = astGrep;\n\n      // Read current content\n      let content: string | Buffer;\n      try {\n        content = await filesystem.readFile(path, { encoding: 'utf-8' });\n      } catch (error) {\n        if (error instanceof FileNotFoundError) {\n          span.end({ success: false });\n          return `File not found: ${path}. Use the write file tool to create it first.`;","sourceCodeStart":430,"sourceCodeEnd":466,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/tools/ast-edit.ts#L430-L466","documentation":"Thrown by the ast_edit workspace tool when the workspace filesystem is in read-only mode. AST-based code transformations mutate files, so they are blocked before loading ast-grep. The error carries code READ_ONLY via WorkspaceReadOnlyError with the offending operation name.","triggerScenarios":"Invoking the ast_edit tool (with path, transform, pattern inputs) on a workspace whose filesystem provider was configured read-only, or whose readOnly flag is true at execution time.","commonSituations":"Running agents against a read-only workspace/deployment (e.g. production inspection, sandboxed preview); forgetting to enable write access for an editing agent.","solutions":["Configure the workspace filesystem as writable (remove readOnly / supply a writable provider)","Mount or point the workspace at a writable copy of the files instead of a read-only source","Skip ast_edit in read-only deployments and surface file changes through a separate write workflow","Check workspace.filesystem read-only status before invoking edit tools to fail gracefully"],"exampleFix":"// before\nnew Workspace({ filesystem: createFilesystem({ root, readOnly: true }) });\n// after\nnew Workspace({ filesystem: createFilesystem({ root, readOnly: false }) });","handlingStrategy":"validation","validationCode":"if (workspace.filesystem && workspace.filesystem.readOnly) {\n  throw new Error('ast_edit 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 astEditTool.execute({ context: { path, transform, pattern }, ... });\n} catch (e: any) {\n  if (e?.code === 'READ_ONLY' || /read-only mode/i.test(e?.message ?? '')) {\n    return { skipped: true, reason: 'workspace is read-only' };\n  }\n  throw e;\n}","preventionTips":["Check filesystem.readOnly before registering mutation tools","Provision writable workspaces for editing agents","Run code-edit agents against writable clones, not production mounts","Surface read-only status in agent instructions/UI"],"tags":["read-only","workspace","ast-edit","filesystem"],"backgroundTag":"workspace-read-only","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}