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

There was an error loading a Vagrantfile. The file being loa

Error message

There was an error loading a Vagrantfile. The file being loaded and the error message are shown below. This is usually caused by a syntax error.

Path: %{path}
Line number: %{line}
Message: %{exception_class}: %{message}

What it means

Raised as Vagrant::Errors::VagrantfileLoadError from Config::Loader#procs_for_path (lib/vagrant/config/loader.rb:313) when Kernel.load(path) raises a generic Exception that is not SyntaxError, SystemExit, or a known Vagrant::Errors::VagrantError. It reports the exception class, message, and the best-effort path/line parsed from the backtrace. This covers the top-level execution of the Vagrantfile, distinct from the configure-block evaluation covered by VagrantfileNameError and from parse errors covered by VagrantfileSyntaxError.

Source

Thrown at lib/vagrant/config/loader.rb:313

            # Continue raising known Vagrant errors since they already
            # contain well worded error messages and context.
            raise
          rescue Exception => e
            @logger.error("Vagrantfile load error: #{e.message}")
            @logger.error(e.backtrace.join("\n"))

            line = "(unknown)"
            if e.backtrace && e.backtrace[0]
              e.backtrace[0].split(":").each do |part|
                if part =~ /\d+/
                  line = part.to_i
                  break
                end
              end
            end

            # Report the generic exception
            raise Errors::VagrantfileLoadError,
              path: path,
              line: line,
              exception_class: e.class,
              message: e.message
          end
        end
      end
    end
  end
end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Read the Exception class and Message fields in the error, then open the reported Path and Line number
2. For LoadError on a gem: prefer a Vagrant plugin (vagrant plugin install <name>) plus Vagrant.has_plugin? guards instead of raw require
3. For Errno::* on file access: guard with File.exist? and build paths relative to the Vagrantfile (File.expand_path(..., __FILE__))
4. Re-run `vagrant validate` to confirm the file loads cleanly

Example fix

# before
require "aws-sdk"   # LoadError: cannot load such file -- aws-sdk
Vagrant.configure("2") do |config|
  # ...
end

# after
# vagrant plugin install vagrant-aws
raise "vagrant-aws plugin required" unless Vagrant.has_plugin?("vagrant-aws")
Vagrant.configure("2") do |config|
  # ...
end

# Require nothing at load time you have not verified is present
%w[json yaml].each do |lib|
  begin
    require lib
  rescue LoadError => e
    abort "Vagrantfile dependency missing: #{e.message}"
  end
end

begin
  env = Vagrant::Environment.new(cwd: dir)
  env.vagrantfile
rescue Vagrant::Errors::VagrantfileLoadError => e
  abort "#{e.extra_data[:exception_class]} at #{e.extra_data[:path]}:#{e.extra_data[:line]}: #{e.extra_data[:message]}"
end

When it happens

Trigger: A Vagrantfile that parses but whose top-level code raises: require "aws-sdk" when the gem is not installed (LoadError), File.read("boxes.json") on a missing file (Errno::ENOENT), NoMethodError on nil at top level, or any custom raise outside Vagrant.configure blocks — all surfaced while Kernel.load executes the file.

Common situations: Requiring third-party gems directly in a Vagrantfile instead of using plugins; reading environment-specific JSON/YAML files that are absent on a new checkout; shell-style logic at the top of the file failing on a different OS.

Related errors

• There are errors in the configuration of this machine. Pleas
• There was an error loading a Vagrantfile. The file being loa
• The Vagrantfile defines more than one 'push' strategy. Pleas
• The specified Vagrantfile to clone from was not found. Pleas
• The defined alias is not valid. Please review the informatio

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