hashicorp/vagrant · error · VagrantPlugins::HyperV::Errors::SystemAccessRequired

Hyper-V access check has failed for the configured destinati

Error message

Hyper-V access check has failed for the configured destination. This
is usually caused by running on a non-system drive which is missing
required permissions. Running the following command may resolve the
problem:

  icacls.exe %{root_dir} /T /Q /grant "NT AUTHORITY\SYSTEM:(IO)(CI)(F)"

What it means

The Hyper-V provider's CheckAccess action runs the check_hyperv_access PowerShell script against the machine's data dir (WSL-translated to a Windows path). If Hyper-V reports the path inaccessible (result false), SystemAccessRequired is raised with root_dir; the message prescribes granting NT AUTHORITY\SYSTEM full control over that tree via icacls.exe.

Source

Thrown at plugins/providers/hyperv/action/check_access.rb:18

# Copyright IBM Corp. 2010, 2025
# SPDX-License-Identifier: BUSL-1.1

module VagrantPlugins
  module HyperV
    module Action
      class CheckAccess
        def initialize(app, env)
          @app    = app
        end

        def call(env)
          env[:ui].output("Verifying Hyper-V is accessible...")
          result = env[:machine].provider.driver.execute(:check_hyperv_access,
            "Path" => Vagrant::Util::Platform.wsl_to_windows_path(env[:machine].data_dir).gsub("/", "\\")
          )
          if !result["result"]
            raise Errors::SystemAccessRequired,
              root_dir: result["root_dir"]
          end

          @app.call(env)
        end
      end
    end
  end
end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Run the exact icacls command from the message: icacls.exe <root_dir> /T /Q /grant "NT AUTHORITY\SYSTEM:(IO)(CI)(F)"
2. Or relocate the project (and VAGRANT_HOME) to the system drive
3. Re-run `vagrant up` after granting; verify inheritance with `icacls <dir>`

Example fix

# before: project on D:\ with default ACLs -> SystemAccessRequired

# after (admin shell)
icacls.exe D:\projects\demo\.vagrant /T /Q /grant "NT AUTHORITY\SYSTEM:(IO)(CI)(F)"

# preflight: grant SYSTEM access to the data dir before vagrant up (admin shell)
icacls.exe .\.vagrant /T /Q /grant "NT AUTHORITY\SYSTEM:(IO)(CI)(F)"

When it happens

Trigger: `vagrant up --provider=hyperv` when the .vagrant machine data dir sits on a non-system drive whose ACLs do not let the SYSTEM account (used by Hyper-V for import/export) access the files.

Common situations: Projects on secondary drives (D:, E:); restrictive corporate ACLs or disabled inheritance; VAGRANT_HOME relocated to a non-system volume.

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

• The Hyper-V cmdlets for PowerShell are not available! Vagran
• Failed to create the following shared folder on the host sys
• The home directory you specified is not accessible. The home
• The directory Vagrant will use to store local environment-sp
• Vagrant failed to copy the default insecure private key into

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