{"record":{"id":"1b0fb5140905c505","repo":"hashicorp/vagrant","slug":"there-was-an-error-loading-a-vagrantfile-the-file","errorCode":null,"errorMessage":"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.\n\nPath: %{path}\nLine number: %{line}\nMessage: %{message}","messagePattern":"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\\.\n\nPath: %(.+?)\nLine number: %(.+?)\nMessage: %(.+?)","errorType":"exception","errorClass":"Vagrant::Errors::VagrantfileNameError","httpStatus":null,"severity":"error","filePath":"lib/vagrant/config/loader.rb","lineNumber":144,"sourceCode":"              # Get the proper version loader for this version and load\n              version_loader = @versions.get(version)\n              begin\n                version_config = version_loader.load(proc)\n              rescue NameError => e\n                line = \"(unknown)\"\n                path = \"(unknown)\"\n                if e.backtrace && e.backtrace[0]\n                  backtrace_tokens = e.backtrace[0].split(\":\")\n                  path = e.backtrace.first.slice(0, e.backtrace.first.rindex(':')).rpartition(':').first\n                  backtrace_tokens.each do |part|\n                    if part =~ /\\d+/\n                      line = part.to_i\n                      break\n                    end\n                  end\n                end\n\n                raise Errors::VagrantfileNameError,\n                  path: path,\n                  line: line,\n                  message: e.message.sub(/' for .*$/, \"'\")\n              end\n\n              # Store the errors/warnings associated with loading this\n              # configuration. We'll store these for later.\n              version_warnings = []\n              version_errors   = []\n\n              # If this version is not the current version, then we need\n              # to upgrade to the latest version.\n              if version != current_version\n                @logger.debug(\"Upgrading config from version #{version} to #{current_version}\")\n                version_index = @version_order.index(version)\n                current_index = @version_order.index(current_version)\n\n                (version_index + 1).upto(current_index) do |index|","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/lib/vagrant/config/loader.rb#L126-L162","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nVagrant.configure(\"2\") do |config|\n  config.vm.box = box_name   # NameError: undefined local variable or method 'box_name'\nend\n\n# after\nbox_name = \"ubuntu/jammy64\"\nVagrant.configure(\"2\") do |config|\n  config.vm.box = box_name\nend","handlingStrategy":"try-catch","validationCode":"# Cheap smoke test before automation: force Vagrantfile evaluation\nsystem(\"vagrant validate\") or abort \"Vagrantfile failed to load — fix errors above\"","typeGuard":null,"tryCatchPattern":"begin\n  env = Vagrant::Environment.new(cwd: project_dir)\n  cfg = env.vagrantfile.config   # forces configure-block evaluation\nrescue Vagrant::Errors::VagrantfileNameError => e\n  abort \"Vagrantfile #{e.extra_data[:path]}:#{e.extra_data[:line]}: #{e.extra_data[:message]}\"\nend","preventionTips":["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"],"tags":["vagrant","vagrantfile","ruby","nameerror","configuration"],"backgroundTag":"undefined-variable","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}