On SSH authentication failure, give a helpful error message outlining what may have gone wrong.

lib/vagrant/ssh.rb

@@ -1,5 +1,7 @@
 module Vagrant
   class SSH
+    include Vagrant::Util
+
     class << self
       def connect(opts={})
         options = {}
@@ -11,9 +13,9 @@ module Vagrant
       end
 
       def execute(opts={})
-        Net::SSH.start(Vagrant.config.ssh.host, 
-                       Vagrant.config[:ssh][:username], 
-                       opts.merge( :port => port, 
+        Net::SSH.start(Vagrant.config.ssh.host,
+                       Vagrant.config[:ssh][:username],
+                       opts.merge( :port => port,
                                    :keys => [Vagrant.config.ssh.private_key_path])) do |ssh|
           yield ssh
         end
@@ -40,6 +42,22 @@ module Vagrant
 
         check_thread.join(Vagrant.config.ssh.timeout)
         return check_thread[:result]
+      rescue Net::SSH::AuthenticationFailed
+        error_and_exit(<<-msg)
+SSH authentication failed! While this could be due to a variety of reasons,
+the two most common are: private key path is incorrect or you're using a box
+which was built for Vagrant 0.1.x.
+
+Vagrant 0.2.x dropped support for password-based authentication. If you're
+tring to `vagrant up` a box which does not support Vagrant's private/public
+keypair, then this error will be raised. To resolve this, read the guide
+on converting base boxes from password-based to keypairs here:
+
+http://vagrantup.com/docs/converting_password_to_key_ssh.html
+
+If the box was built for 0.2.x and contains a custom public key, perhaps
+the path to the private key is incorrect. Check your `config.ssh.private_key_path`.
+msg
       end
 
       def port(opts={})

test/vagrant/ssh_test.rb

@@ -8,8 +8,8 @@ class SshTest < Test::Unit::TestCase
   context "connecting to SSH" do
     test "should call exec with defaults when no options are supplied" do
       ssh = Vagrant.config.ssh
-      ssh_exec_expect(Vagrant::SSH.port, 
-                      Vagrant.config.ssh.private_key_path, 
+      ssh_exec_expect(Vagrant::SSH.port,
+                      Vagrant.config.ssh.private_key_path,
                       Vagrant.config.ssh.username,
                       Vagrant.config.ssh.host)
       Vagrant::SSH.connect
@@ -104,6 +104,12 @@ class SshTest < Test::Unit::TestCase
       Vagrant::SSH.expects(:execute).with(:timeout => Vagrant.config.ssh.timeout).yields(true)
       assert Vagrant::SSH.up?
     end
+
+    should "error and exit if a Net::SSH::AuthenticationFailed is raised" do
+      Vagrant::SSH.expects(:execute).raises(Net::SSH::AuthenticationFailed)
+      Vagrant::SSH.expects(:error_and_exit).once
+      Vagrant::SSH.up?
+    end
   end
 
   context "getting the ssh port" do