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

The requested Vagrant action is locked. This may be caused b

Error message

The requested Vagrant action is locked. This may be caused
by other Vagrant processes attempting to do a similar action.

Lock file path: %{lock_file_path}

What it means

Vagrant::Util::FileMutex#lock calls flock(File::LOCK_EX | File::LOCK_NB) on the mutex file; when the non-blocking exclusive lock cannot be granted (flock returns false because another process holds it) it raises VagrantLocked with the lock file path. Vagrant serializes environment/machine actions this way, so the error means another live Vagrant process is mid-action on the same target.

Source

Thrown at lib/vagrant/util/file_mutex.rb:31

      end

      # Execute provided block within lock and unlock
      # when completed
      def with_lock(&block)
        lock
        begin
          block.call
        rescue => e
          raise e
        ensure
          unlock
        end
      end

      # Attempt to acquire the lock
      def lock
        if lock_file.flock(File::LOCK_EX|File::LOCK_NB) === false
          raise Errors::VagrantLocked, lock_file_path: @mutex_path
        end
      end

      # Unlock the file
      def unlock
        lock_file.flock(File::LOCK_UN)
        lock_file.close
        File.delete(@mutex_path) if File.file?(@mutex_path)
      end

      protected

      def lock_file
        return @lock_file if @lock_file && !@lock_file.closed?
        @lock_file = File.open(@mutex_path, "w+")
      end
    end
  end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Wait for the in-flight Vagrant command to finish, then re-run
2. Find the holder via `lsof <lock_file_path>` (or fuser -v) and kill it only if it is genuinely hung
3. Serialize access in tooling (queue, flock wrapper, make) so two vagrant invocations never overlap on one environment

def lock_held?(path)
  return false unless File.exist?(path)
  f = File.open(path, 'a+')
  got = f.flock(File::LOCK_EX | File::LOCK_NB)
  f.flock(File::LOCK_UN) unless got == false
  f.close
  got == false
end

sleep until !lock_held?(mutex_path)

tries = 0
begin
  mutex.with_lock { do_work }
rescue Vagrant::Errors::VagrantLocked
  tries += 1
  sleep 2**tries
  retry if tries < 5
end

When it happens

Trigger: Two Vagrant commands racing on the same project/environment — `vagrant up` in one terminal while `vagrant reload`/`halt` runs in another; an IDE plugin or background daemon invoking vagrant concurrently with your shell.

Common situations: Overlapping automation scripts without serialization; a previous vagrant process that hung while still holding the flock; CI jobs sharing one checkout.

Related errors

• Vagrant attempted to acquire a lock named '%{name}', but thi
• Download to global Vagrant location already in progress. Thi

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