hashicorp/vagrant · error · Vagrant::Errors::MachineFolderNotAccessible

Vagrant attempted to clean the machine folder for the machin

Error message

Vagrant attempted to clean the machine folder for the machine '%{name}'
but does not have permission to read the following path:

%{path}

Please ensure that Vagrant has the proper permissions to access the path
above. You may need to grant this permission to the terminal emulator
running Vagrant as well.

What it means

During VirtualBox cleanup (the CleanMachineFolder action runs before destroy/re-up), Vagrant globs the VirtualBox default machine folder and deletes leftover per-VM subfolders. If any file operation underneath raises Errno::EPERM, it is rescued and re-raised as MachineFolderNotAccessible with the offending folder path. The intent is to abort with a clear message instead of a raw EPERM backtrace.

Source

Thrown at plugins/providers/virtualbox/action/clean_machine_folder.rb:24

module VagrantPlugins
  module ProviderVirtualBox
    module Action
      # Cleans up the VirtualBox machine folder for any ".xml-prev"
      # files which VirtualBox may have left over. This is a bug in
      # VirtualBox. As soon as this is fixed, this middleware can and
      # will be removed.
      class CleanMachineFolder
        def initialize(app, env)
          @app = app
        end

        def call(env)
          machine_folder = env[:machine].provider.driver.read_machine_folder

          begin
            clean_machine_folder(machine_folder)
          rescue Errno::EPERM
            raise Vagrant::Errors::MachineFolderNotAccessible,
              name: env[:machine].name,
              path: machine_folder
          end

          @app.call(env)
        end

        def clean_machine_folder(machine_folder)
          folder = File.join(machine_folder, "*")

          # Small safeguard against potentially unwanted rm-rf, since the default
          # machine folder will typically always be greater than 10 characters long.
          # For users with it < 10, out of luck?
          return if folder.length < 10

          Dir[folder].each do |f|
            next unless File.directory?(f)

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Run the same vagrant command from an elevated (Administrator) terminal or the same user that created the VMs
  2. Fix ownership/ACLs on the printed path: `takeown /f "<path>" /r` + `icacls "<path>" /grant <user>:(OI)(CI)F` on Windows, or `sudo chown -R $USER <path>` on Unix hosts
  3. Exclude the VirtualBox machine folder (default ~/VirtualBox VMs) from antivirus real-time scanning and OneDrive sync
  4. As a last resort delete the stale subfolder manually, then re-run vagrant destroy/up

Example fix

# before: normal shell, files owned by admin
# vagrant destroy -> MachineFolderNotAccessible path=C:\Users\admin\VirtualBox VMs

# after (Windows, elevated PowerShell):
# takeown /f "C:\Users\admin\VirtualBox VMs" /r
# icacls "C:\Users\admin\VirtualBox VMs" /grant youruser:(OI)(CI)F /t
# vagrant destroy
Defensive patterns

Strategy: try-catch

Validate before calling

# confirm the default machine folder is writable before destroy/up
folder = `VBoxManage list systemproperties`[/Default machine folder:\s+(.+?)\n/, 1].to_s.strip
raise "Not writable: #{folder}" unless File.writable?(folder)
# deeper probe (Windows may allow File.writable? but deny delete):
probe = File.join(folder, '.vagrant_probe')
FileUtils.touch(probe); FileUtils.rm(probe) rescue raise "EPERM expected under #{folder}"

Try / catch

begin
  machine.action(:destroy)
rescue Vagrant::Errors::MachineFolderNotAccessible => e
  warn "Fix ACLs on #{e.extra_data[:path]} (takeown/icacls), delete stale folders manually, then retry"
  # safe to continue: cleanup failed but the destroy itself can be retried
end

Prevention

When it happens

Trigger: `vagrant destroy` or `vagrant up` on VirtualBox where File.delete/FileUtils operations inside clean_machine_folder(machine_folder) hit EPERM — files owned by another user, locked by a process, or on a directory the current user cannot read.

Common situations: VMs originally created from an elevated/admin terminal and now cleaned from a normal one; antivirus or backup software holding handles on .vbox/.vdi files; the default machine folder moved onto OneDrive/protected storage on Windows; POSIX-inherited ownership after copying VM folders between users.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

AI-assisted analysis of hashicorp/vagrant@35f3160f4a (2026-08-21). Data as JSON: /api/errors/6ced4ad7c409aeb8. Report an issue: GitHub.