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

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 an invalid or undefined variable.

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

What it means

Raised as Vagrant::Errors::VagrantfileNameError from Vagrant::Config::Loader#load (lib/vagrant/config/loader.rb:144) when evaluating a Vagrant.configure block raises NameError, meaning the block references an undefined variable, method, or constant. The loader rescues only NameError, extracts the file path and line number from the first backtrace frame, and strips Ruby's trailing " for #<...>" context (e.message.sub(/' for .*$/, "'")) so the report points cleanly at the Vagrantfile line. Any vagrant command that loads full configuration (up, status, ssh, validate) goes through this path.

Source

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

              # Get the proper version loader for this version and load
              version_loader = @versions.get(version)
              begin
                version_config = version_loader.load(proc)
              rescue NameError => e
                line = "(unknown)"
                path = "(unknown)"
                if e.backtrace && e.backtrace[0]
                  backtrace_tokens = e.backtrace[0].split(":")
                  path = e.backtrace.first.slice(0, e.backtrace.first.rindex(':')).rpartition(':').first
                  backtrace_tokens.each do |part|
                    if part =~ /\d+/
                      line = part.to_i
                      break
                    end
                  end
                end

                raise Errors::VagrantfileNameError,
                  path: path,
                  line: line,
                  message: e.message.sub(/' for .*$/, "'")
              end

              # Store the errors/warnings associated with loading this
              # configuration. We'll store these for later.
              version_warnings = []
              version_errors   = []

              # If this version is not the current version, then we need
              # to upgrade to the latest version.
              if version != current_version
                @logger.debug("Upgrading config from version #{version} to #{current_version}")
                version_index = @version_order.index(version)
                current_index = @version_order.index(current_version)

                (version_index + 1).upto(current_index) do |index|

View on GitHub (pinned to 35f3160f4a)

Solutions

Open the Path and Line number printed in the error and fix the undefined variable, method, or constant on that exact line
If the name is a helper, define it above Vagrant.configure in the same file, or require the file that defines it before Vagrant.configure runs
If it comes from a plugin, install it (vagrant plugin install <name>) or guard the call with if Vagrant.has_plugin?("...")
Re-run `vagrant status` or `vagrant validate` after each fix to confirm the Vagrantfile loads

Example fix

# before
Vagrant.configure("2") do |config|
  config.vm.box = box_name   # NameError: undefined local variable or method 'box_name'
end

# after
box_name = "ubuntu/jammy64"
Vagrant.configure("2") do |config|
  config.vm.box = box_name
end

Defensive patterns

Strategy: try-catch

Validate before calling

# Cheap smoke test before automation: force Vagrantfile evaluation
system("vagrant validate") or abort "Vagrantfile failed to load — fix errors above"

Try / catch

begin
  env = Vagrant::Environment.new(cwd: project_dir)
  cfg = env.vagrantfile.config   # forces configure-block evaluation
rescue Vagrant::Errors::VagrantfileNameError => e
  abort "Vagrantfile #{e.extra_data[:path]}:#{e.extra_data[:line]}: #{e.extra_data[:message]}"
end

Prevention

Define helper methods/variables above Vagrant.configure so they are bound before the block runs
Guard plugin-dependent code with Vagrant.has_plugin?("name") instead of calling plugin methods directly
Run `vagrant validate` in CI before any vagrant up/provision step
After renaming any variable referenced inside Vagrant.configure, grep the Vagrantfile for stale names

When it happens

Trigger: Calling Config::Loader#load (directly or via Vagrant::Environment#load_config / vagrant CLI commands) where a captured configure proc raises NameError when instance_eval'd by the version loader: config.vm.box = box_nmae (typo), a call to a helper method never defined (lookup_box()), or a constant from a gem that was never required inside Vagrant.configure("2") do |config| ... end.

Common situations: Refactoring a Vagrantfile and forgetting to move helper methods defined at the bottom of the file; copy-pasted Vagrantfiles that depend on plugins or ENV-derived helpers that are absent; upgrading Vagrant or a plugin that used to define a method the file calls; typos in variable names after renaming.

Related errors

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