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

FreeBSD hosts do not support sharing directories with whites

Error message

FreeBSD hosts do not support sharing directories with whitespace in
their path. Please adjust your path accordingly.

What it means

Raised as Vagrant::Errors::VagrantError with `_key: :freebsd_nfs_whitespace` in the FreeBSD host cap (plugins/hosts/freebsd/cap/nfs.rb:16). FreeBSD's exports(5) format cannot express a directory containing whitespace, so before delegating to the BSD nfs_export, Vagrant scans every folder's :hostpath against /\s+/ and refuses to touch /etc/exports if any match. The work then defers to HostBSD::Cap::NFS.

Source

Thrown at plugins/hosts/freebsd/cap/nfs.rb:16

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

require "vagrant/util"
require "vagrant/util/retryable"

require Vagrant.source_root.join("plugins", "hosts", "bsd", "cap", "nfs")

module VagrantPlugins
  module HostFreeBSD
    module Cap
      class NFS
        def self.nfs_export(environment, ui, id, ips, folders)
          folders.each do |folder_name, folder_values|
            if folder_values[:hostpath] =~ /\s+/
              raise Vagrant::Errors::VagrantError,
                _key: :freebsd_nfs_whitespace
            end
          end

          HostBSD::Cap::NFS.nfs_export(environment, ui, id, ips, folders)
        end

        def self.nfs_exports_template(environment)
          "nfs/exports_bsd"
        end

        def self.nfs_restart_command(environment)
          ["sudo", "/etc/rc.d/mountd", "onereload"]
        end
      end
    end
  end
end

View on GitHub (pinned to 35f3160f4a)

Solutions

Rename or move the host directory so the path contains no whitespace
Create a whitespace-free symlink to the real directory (`ln -s "/path/with space" /usr/local/nospace`) and use the symlink as the synced-folder host path
Switch that folder to another synced-folder type if renaming is impossible

Example fix

# before
config.vm.synced_folder "/home/me/My Projects", "/project", type: "nfs"
# after — symlink without whitespace (run once on the host)
# ln -s "/home/me/My Projects" /home/me/myprojects
config.vm.synced_folder "/home/me/myprojects", "/project", type: "nfs"

Defensive patterns

Strategy: validation

Validate before calling

# In your Vagrantfile / wrapper on FreeBSD, reject whitespace host paths up front
host_paths = ["/home/me/My Projects"] # collected from your synced_folder config
host_paths.each do |p|
  abort "FreeBSD NFS cannot use whitespace paths: #{p}" if p =~ /\s/
end

Try / catch

begin
  HostFreeBSD::Cap::NFS.nfs_export(env, ui, id, ips, folders)
rescue Vagrant::Errors::VagrantError => e
  raise if e.message !~ /whitespace/
  # else: symlink the path and retry with the whitespace-free alias
end

Prevention

Keep FreeBSD project paths whitespace-free by convention
Create symlinks for inherited spaced paths and point the Vagrantfile at them
Add a lint check for synced-folder paths in CI before `vagrant up`

When it happens

Trigger: On a FreeBSD host, any `type: "nfs"` synced_folder whose expanded host path matches /\s+/ — a space or tab anywhere in the path, e.g. "/home/user/My Projects".

Common situations: Projects living under directories like "My Documents" or "VirtualBox VMs"; paths interpolated from usernames with spaces; paths copied from Windows shares keeping spaces.

Related errors

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