mastra-ai/mastra · error · WorkspaceReadOnlyError

READ_ONLY

READ_ONLY

Error message

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

What it means

Thrown by the delete-file workspace tool when the filesystem is read-only. Deleting files or directories mutates the workspace, so the operation is rejected before any stat/rmdir/unlink call. Code is READ_ONLY via WorkspaceReadOnlyError naming the 'delete' operation.

Source

Thrown at packages/core/src/workspace/tools/delete-file.ts:33

      .boolean()
      .optional()
      .default(false)
      .describe('If true, delete directories and their contents recursively. Required for non-empty directories.'),
  }),
  execute: async ({ path, recursive }, context) => {
    const { workspace, filesystem } = requireFilesystem(context);
    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.FILESYSTEM.DELETE);

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

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

      const stat = await filesystem.stat(path);
      if (stat.type === 'directory') {
        await filesystem.rmdir(path, { recursive, force: recursive });
      } else {
        await filesystem.deleteFile(path);
      }

      span.end({ success: true });
      return `Deleted ${path}`;
    } catch (err) {
      span.error(err);
      throw err;
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

1. Switch the filesystem provider to writable mode for the workspace
2. Perform deletions in an environment with write permissions (dev workspace or writable mount)
3. Make the target path writable at the OS/provider level if the read-only flag reflects mount permissions
4. Handle READ_ONLY in tool results and skip deletion steps gracefully

Example fix

// before
filesystem: createFilesystem({ root, readOnly: true })
// after
filesystem: createFilesystem({ root, readOnly: false })

if (workspace.filesystem.readOnly) {
  throw new Error('delete unavailable: workspace is read-only');
}

function canDelete(fs: WorkspaceFilesystem | undefined): fs is WorkspaceFilesystem & { readOnly: false } {
  return !!fs && fs.readOnly === false;
}

try {
  await deleteTool.execute({ context: { path, recursive }, ... });
} catch (e: any) {
  if (e?.code === 'READ_ONLY') return { skipped: true, reason: 'read-only workspace' };
  throw e;
}

When it happens

Trigger: Invoking the delete tool with path (and optional recursive) on a workspace whose filesystem.readOnly is true.

Common situations: Agents pointed at immutable deployments or mounted read-only volumes; cleanup routines running in preview/production-inspection environments.

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