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

The push strategy '%{name}' is not defined in the Vagrantfil

Error message

The push strategy '%{name}' is not defined in the Vagrantfile. Defined
strategy names are:

    %{pushes}

What it means

Raised as Vagrant::Errors::PushStrategyNotDefined from Vagrant::Environment#push (lib/vagrant/environment.rb:697) when the requested name is not a key in vagrantfile.config.push.__compiled_pushes — the set of `config.push.define "name"` blocks in the Vagrantfile. The error lists the names that are defined so you can pick one.

Source

Thrown at lib/vagrant/environment.rb:697

    # This executes the push with the given name, raising any exceptions that
    # occur.
    #
    # @param name [String] Push plugin name
    # @param manager [Vagrant::Plugin::Manager] Plugin Manager to use,
    # defaults to the primary one registered but parameterized so it can be
    # overridden in server mode
    #
    # @see VagrantPlugins::CommandServe::Service::PushService Server mode behavior
    #
    # Precondition: the push is not nil and exists.
    def push(name, manager: Vagrant.plugin("2").manager)
      @logger.info("Getting push: #{name}")

      name = name.to_sym

      pushes = self.vagrantfile.config.push.__compiled_pushes
      if !pushes.key?(name)
        raise Vagrant::Errors::PushStrategyNotDefined,
          name: name,
          pushes: pushes.keys
      end

      strategy, config = pushes[name]
      push_registry = manager.pushes
      klass, _ = push_registry.get(strategy)
      if klass.nil?
        raise Vagrant::Errors::PushStrategyNotLoaded,
          name: strategy,
          pushes: push_registry.keys
      end

      klass.new(self, config).push
    end

    # The list of pushes defined in this Vagrantfile.
    #

View on GitHub (pinned to 35f3160f4a)

Solutions

Compare the name you passed against the "Defined strategy names" list printed in the error
Add the missing definition in Vagrant.configure: config.push.define "<name>" do |push| ... end
If the push is defined in another project's Vagrantfile, run vagrant push from that project directory
Commit and pull the Vagrantfile changes that define the push so all machines see it

Example fix

# before — Vagrantfile defines nothing, so `vagrant push staging` fails
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
end

# after
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  config.push.define "staging" do |push|
    push.path = "."
  end
end

Defensive patterns

Strategy: validation

Validate before calling

name = "staging"
defined = env.pushes   # Array<Symbol> from config.push.__compiled_pushes
unless defined.include?(name.to_sym)
  abort "No push named '#{name}'; defined: #{defined.join(', ')}"
end
env.push(name)

Try / catch

begin
  env.push(name)
rescue Vagrant::Errors::PushStrategyNotDefined => e
  abort "Unknown push '#{e.extra_data[:name]}'; pick one of: #{Array(e.extra_data[:pushes]).join(', ')}"
end

Prevention

Source push names from a single config so scripts and Vagrantfile cannot drift
List available pushes via env.pushes before prompting users for a name
Commit push definitions together with the deploy scripts that reference them

When it happens

Trigger: Running `vagrant push staging` (or calling env.push("staging")) when the Vagrantfile contains no `config.push.define "staging" do |push| ... end` block, or the name is mistyped/renamed, or you are in a directory served by a fallback Vagrantfile (home/root) that defines no pushes.

Common situations: Deploying from memory with a stale stage name after the Vagrantfile was refactored; running push from the wrong project directory; teammates' checkouts missing the push definition because it lives in an uncommitted file.

Related errors

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