Need help? Let us know on GitHub! Don’t hesitate to open a new issue on GitHub if you run into trouble or have any tips that we need to know. There’s no need to spend hours trying to fix a local install when a VVV contributor can point you in the right direction in minutes. Also, check out our slack workspace in the menu.
Common Problems
Missing Hosts/vvv.test
If you’re having trouble reaching VVV hosts in the browser, take a look at the hosts troubleshooting article
Already Fixed Problems
If provisioning fails, there’s a high chance it has already been fixed. Update your VVV to the newest version.
If updating to the latest version does not help, try the develop
branch:
Switch to develop
:
git checkout develop
Then make sure it’s the latest develop
:
git pull
And reprovision:
vagrant up --provision
I Installed Docker On Windows
Docker uses a Hyper-V virtual machine as a Linux container host, but VirtualBox and Hyper-V do not work together. You may be lucky and find that VirtualBox pretends it works but uses Hyper-V behind the scenes, but if you had already set up VVV then you may have issues.
To work around Hyper-V though you have three options
Switch VVV to Docker ( best )
You will need to recreate your VM, so vagrant destroy
, then change the provider
in config/config.yml
to docker
( provider: docker
) and reprovision.
Switch VVV to Hyper-V
You will need to recreate your VM, so vagrant destroy
, then change the provider
in config/config.yml
to hyperv
( provider: hyperv
) and reprovision.
Use WSL for Docker
WSL does not use Hyper-V and can provide faster performance when used with Docker.
Microsoft have a tutorial on how to do this with docker desktop here, once done do not forget to turn off Hyper-V in windows features and restart. You may need to back up any data in docker containers before doing this.
SSL/TLS Issues
For your browser to accept https://
addresses on VVV sites, it needs to trust the VVV root certificate. This article will explain how to add the VVV root certificate on your computer..
VirtualBox Failing to Install on MacOS the first time around
On recent versions of MacOS, you need to go into the system preferences to the security panel. Here it will be complaining that an unverified piece of software from Oracle named VirtualBox tried to install things. Unlock the settings pane and approve/allow this, then re-run the installer and all should be fine.
For whatever reason, MacOS doesn’t pop up the usual dialog notifying you when the VirtualBox installer attempts this for the first time, and the VirtualBox installer doesn’t tell you what to do.
How Do I work with Private Gitlab/GitHub repositories?
VVV turns on SSH forwarding, so if you can access it on the host, so can VVV. This might not work though, so:
- Make sure you’re using the SSH URLs for your git repos, not the HTTPS versions, e.g.
git@github.com:Varying-Vagrant-Vagrants/VVV.git
- Run
ssh -T git@github.com
on your host to verify you can SSH to GitHub, usessh -T git@gitlab.net
for GitLab, etc- If this fails, you need to fix it on your host machine before trying to fix VVV, look up how to set up SSH keys on GitHub docs
- GitHub has articles here on how to use/add/setup SSH keys, GitLab/BitBucket will have similar instructions that are mostly identical
- Use
vagrant ssh
to enter the VM and run the above command to test if the VM can SSH to GitHub/GitLab- If this fails, but it works on the host, then perhaps SSH Agent forwarding isn’t turned on, or some other step needs to happen
- Visit this super useful article from GitHub on debugging/setting up SSH Forwarding on your host
You might also find it helpful to set up the SSH config, normally found at ~/.ssh/config
with the following:
Host *
UseKeychain yes
AddKeysToAgent yes
Windows users will need an SSH client installed, luckily installing Git does this for most users.
SSH Timeout During a Vagrant Provision
This is a generic error that can indicate multiple things, including:
- An unexpected error in the provisioner
- Failure to set up the connection between Vagrant and the running VM ( a handful of versions of Vagrant failed to install the necessary keys inside the VM, updating Vagrant, destroying the box, and doing a clean provision should resolve this )
- Local network IP clashes
- Firewalls
- Unusual network configurations
- Many other possible problems
If this happens, do the following, and provide the results when asking for help.
- Run
vagrant ssh
, if this works and you’re able to get inside the VVV machine and run commands that is useful information, and may allow you to manually run the commands to bring up nginx and PHP - Halt the machine with
vagrant halt
and turn it back on in debugging mode usingvagrant up --provision --debug > vagrant.log
. The log file may then reveal errors that might not show in the terminal. Send this file when reporting this problem. - In a worst case scenario you can use the VirtualBox GUI to stop the virtual machine and delete it, you may get useful debug information if you open the VM with a visual interface.
Vagrant Plugin Install Issues and Broken Vagrant Upgrades
When updating from Vagrant 1.x to 2.x, Vagrants bundler can throw errors, here’s an example:
$ vagrant plugin install vagrant-hostsupdater
Installing the 'vagrant-hostsupdater' plugin. This can take a few minutes...
Bundler, the underlying system Vagrant uses to install plugins,
reported an error. The error is shown below. These errors are usually
caused by misconfigured plugin installations or transient network
issues. The error from Bundler is:
conflicting dependencies ffi (= 1.9.18) and ffi (= 1.9.14)
Activated ffi-1.9.14
which does not match conflicting dependency (= 1.9.18)
Conflicting dependency chains:
ffi (= 1.9.14), 1.9.14 activated
versus:
ffi (= 1.9.18)
Gems matching ffi (= 1.9.18):
ffi-1.9.18-x64-mingw32
When this happens, the solution is to completely uninstall Vagrant, then reinstall. Do this either using the uninstall tool in the DMG on MacOS, or the standard uninstaller on Windows.
Corrupt VM
It’s possible that the Virtual Machine file system may become corrupted. This might happen if your VM didn’t shut down correctly, perhaps there was a power cut or your laptop ran out of power unexpectedly.
In this scenario, your files should be safe on the host filesystem. If you have run vagrant halt
recently, a database backup will be available. Using these, the site can be recovered from a fresh VVV box.
Follow the starting from fresh instructions at the top of this document to recover.
For more information on backups, see the backups section below.
Common Causes of Problems
Typos in your config file
If there’s a typo or syntax error in config/config.yml
the provisioner will fail. Make sure the file is valid YAML when making changes to this file.
Out of Date VVV
VVV is an active project, but if it isn’t up to date you might suffer from bugs that have already been fixed.
Updating is often as simple as doing a git pull
and restarting/reprovisioning VVV with vagrant up --provision
. However, occasionally a new version of VVV may require the underlying software to be updated first, so it is wise to check the News & Changelog before doing this.
If you downloaded a zip originally, you can convert your install to use git and then perform the update process above.
Out of Date Software
Mismatched Virtualbox and Guest additions can cause problems, as can older versions of Vagrant. When troubleshooting a problem, update to the latest versions of software, then verify the problem still exists after a vagrant halt; vagrant up --provision
Local Network IP Clashes
The network configuration picks an IP of 192.168.50.4
. It could cause conflicts on your existing network if you are on a 192.168.50.x
subnet already. You can configure any IP address in the Vagrantfile
and it will be used on the next vagrant up --provision
.
Vagrant and VirtualBox
VVV relies on the stability of both Vagrant and VirtualBox. These caveats are common to Vagrant environments and are worth noting:
- If the VVV folder is renamed or moved it may break.
- But if you destroy VVV with
vagrant destroy
before moving/renaming, then there will be no issues.
- But if you destroy VVV with
- If VirtualBox is uninstalled, VVV will break.
- If Vagrant is uninstalled, VVV will break.
Memory Allotment
The default memory allotment for the VVV virtual machine is 2048MB. If you would like to raise or lower this value to better match your system requirements, a you can do so with the vm_config section of config/config.yml
is in the wiki.
Keep in mind that if your system only has 2GB of RAM, then you won’t be able to assign 2GB to VVV, you still need some spare for the operating system/browser/editor/etc to use. Reducing the RAM given the VVV might prevent some site templates from working, in particular the WP Core development site template.
64bit Ubuntu and Older CPUs
Since version 1.2.0, VVV has used a 64bit version of Ubuntu. Some older CPUs (such as the popular Intel Core 2 Duo series) do not support this. Changing the line config.vm.box = "ubuntu/trusty64"
to "ubuntu/trusty32"
in the Vagrantfile
before vagrant up
will provision a 32bit version of Ubuntu that will work on older hardware.
Strange letters (like accented) in Windows user name
It is a bug confirmed in Vagrant but there is a workaround in the original bug report.
VirtualBox Cleanup Issues When Destroying and Recreating VVV
If your vagrant up --provision
fails with an error like this:
VirtualBox error:
VBoxManage.exe: error: Could not rename the directory 'C:\Users\<username>\VirtualBox VMs\ubuntu-cloudimg-trusty-vagrant-amd64_1534242157844_99798' to 'C:\Users\<username>\VirtualBox VMs\localdev_306449ed646' to save the settings file (VERR_ALREADY_EXISTS)
VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component SessionMachine, interface IMachine, callee IUnknown
VBoxManage.exe: error: Context: "SaveSettings()" at line 3111 of file VBoxManageModifyVM.cpp
Then the vagrant destroy
command didn’t manage to clean things up properly.
The default location for these files is:
- Windows:
C:\Users\<username>\VirtualBox VMs
- Mac/*nix:
~/VirtualBox VMs
Delete the folder name that matches the path in error above. In the example aboves case it would look similar to this:
....VirtualBox VMs\localdev_306449ed646\
Then go back and run vagrant up --provision
again.
WP CLI Packages provisioner errors
If the tools provisioner errors out while installing or updating WP CLI packages, this may be related to a package problem within WP CLI.
You may use vagrant ssh
from VVV root folder and then wp package
from inside the VM to address the problem based on the error logs produced by the provisioner (the provisioner will point you to the path inside the VM where to find the logs).
For example, older versions of VVV installed the wp-cli/doctor-command
package, but this was removed because it was unreliable and caused issues. If it’s causing you issues, you can run vagrant ssh
to enter the virtual machine, then wp package uninstall wp-cli/doctor-command
to remove the package and fix the problem.
Backups
In the event that you’re stuck or at a loss, VVV tries to generate database backups at VVV/database/backups/*.sql
, with a file for each database.
This coupled with the uploads in the file system should allow the VVV environment to be recreated from a clean slate.
Starting from Fresh
Sometimes a clean, fresh start fixes things.
Note: before doing this you should review the News & Changelog blog. Sometimes you will also need to update the underlying software such as Vagrant or its plugins in order for this process to be successful.
To do a fresh start, run the following commands:
# If you need a fresh start it's probably sensible to make sure you are on the stable branch
git checkout stable
# Make sure this is the latest VVV
git pull
# Turn the machine on (so destroy can run its cleanup)
vagrant up
# Destroy the machine
vagrant destroy
# Make sure we use the latest version of the base box
vagrant box update
# Make sure the recommended vagrant plugins are installed
vagrant plugin install vagrant-goodhosts
# And that they're all up to date
vagrant plugin update
# Start VVV and create the VM from scratch
vagrant up --provision
Connection Resets in Browsers on MacOS Sequoia
Newer versions of MacOS ask if you want to give an application access to the local network, and if you do not allow this then VVV can’t be reached. This can show up if you press Deny in Chrome then try to load vvv.test. To fix this:
- open system preferences
- open the privacy and security section in the sidebar
- Select Local Network in the list
- Enable access for those applications that need to use/interact with VVV