hashicorp/vagrant · error · VagrantPlugins::SyncedFolderSMB::Errors::SMBStartFailed

Vagrant failed to automatically start the SMB service. Ensur

Error message

Vagrant failed to automatically start the SMB service. Ensure the
required services can be started and try again.

Command: %{command}

Stderr: %{stderr}

Stdout: %{stdout}

What it means

SyncedFolderSMB::Errors::SMBStartFailed raised at plugins/hosts/darwin/cap/smb.rb:30. Before using SMB synced folders, the Darwin cap starts the SMB preference daemon: it runs `launchctl list com.apple.smb.preferences`, and when that fails it executes `sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.smb.preferences.plist`; a non-zero exit raises with the exact command and its stderr/stdout.

Source

Thrown at plugins/hosts/darwin/cap/smb.rb:30

        def self.smb_installed(env)
          File.exist?("/usr/sbin/sharing")
        end

        # Check if the required SMB services are loaded and enabled. If they are
        # not, then start them up
        def self.smb_start(env)
          result = Vagrant::Util::Subprocess.execute("pwpolicy", "gethashtypes")
          if result.exit_code == 0 && !result.stdout.include?("SMB-NT")
            @@logger.error("SMB compatible password has not been stored")
            raise SyncedFolderSMB::Errors::SMBCredentialsMissing
          end
          result = Vagrant::Util::Subprocess.execute("launchctl", "list", "com.apple.smb.preferences")
          if result.exit_code != 0
            @@logger.warn("smb preferences service not enabled. enabling and starting...")
            cmd = ["/bin/launchctl", "load", "-w", "/System/Library/LaunchDaemons/com.apple.smb.preferences.plist"]
            result = Vagrant::Util::Subprocess.execute("/usr/bin/sudo", *cmd)
            if result.exit_code != 0
              raise SyncedFolderSMB::Errors::SMBStartFailed,
                command: cmd.join(" "),
                stderr: result.stderr,
                stdout: result.stdout
            end
          end
          result = Vagrant::Util::Subprocess.execute("launchctl", "list", "com.apple.smbd")
          if result.exit_code != 0
            @@logger.warn("smbd service not enabled. enabling and starting...")
            cmd = ["/bin/launchctl", "load", "-w", "/System/Library/LaunchDaemons/com.apple.smbd.plist"]
            result = Vagrant::Util::Subprocess.execute("/usr/bin/sudo", *cmd)
            if result.exit_code != 0
              raise SyncedFolderSMB::Errors::SMBStartFailed,
                command: cmd.join(" "),
                stderr: result.stderr,
                stdout: result.stdout
            end
            Vagrant::Util::Subprocess.execute("/usr/bin/sudo", "/bin/launchctl", "start", "com.apple.smbd")
          end

View on GitHub (pinned to 35f3160f4a)

Solutions

Enable File Sharing manually: System Settings → General → Sharing → File Sharing, then `vagrant reload`
Run the exact Command printed in the error (`sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.smb.preferences.plist`) in Terminal and read its output
Verify sudo works for your user in this shell (no hanging password prompt, not denied by sudoers)
If SMB stays broken, switch the synced folder to another type (nfs, virtualbox, rsync)

Example fix

# before — Vagrantfile
config.vm.synced_folder "/Users/me/data", "/data", type: "smb"
# after — use NFS on macOS when the SMB daemons cannot start
config.vm.synced_folder "/Users/me/data", "/data", type: "nfs"

Defensive patterns

Strategy: validation

Validate before calling

# macOS pre-flight before using SMB synced folders
ok = system("launchctl list com.apple.smb.preferences >/dev/null 2>&1") ||
     system("sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.smb.preferences.plist")
abort "Enable macOS File Sharing (System Settings > Sharing) first" unless ok

Try / catch

begin
  env.machine_action(:up)
rescue VagrantPlugins::SyncedFolderSMB::Errors::SMBStartFailed => e
  puts "could not start SMB service: #{e.data[:command]}\n#{e.data[:stderr]}"
  # offer switching folder type to nfs instead of retrying
  raise
end

Prevention

Enable File Sharing in System Settings before the first SMB synced-folder up
Run vagrant in an interactive shell so sudo prompts work
Prefer NFS for macOS hosts unless SMB credentials are required

When it happens

Trigger: A Vagrantfile with `type: "smb"` synced folders on macOS where the SMB preferences service cannot be enabled — sudo denied or its prompt unavailable (non-interactive shell), SIP/MDM blocking loads of system daemons, or the plist/service damaged.

Common situations: File Sharing never enabled in System Settings → Sharing; CI runners or IDEs without a TTY so sudo cannot prompt; corporate MDM policies restricting launchctl on system daemons; broken com.apple.smb.preferences.plist after an OS update.

Related errors

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