• Home
• Environment
• List of commands
• Data locations
• Environment variables
• Management
• Configure SSH
• Restricting access
• Manage with wp-cli
• Configuration
• Composer - Plugins & Themes
• Custom error pages
• Headless WordPress
• Nginx Web Server
• Server-side PDF printing
• PHP versions
• Serve WebP images
• WordPress Cron
• WordPress Network
• WordPress Rewrites
• Local Development
• Site configuration
• Local development with Docker
• Installing the requirements
• Introduction
• Troubleshooting
• Vagrant workflows
• Data Syncing
• Deploy using Git
• Moving data between instances
• Pulling production
• Staging instances (Shadows)
• Development Tooling
• Compile assets & automate with Gulp
• Debug mails with MailCatcher
• Integration tests using Codeception
• Profiling with Tideways
• Using Git hooks
• Profile runtime with Xdebug & Webgrind

Debugging steps

1. Find the VirtualBox and Vagrant versions. Make sure they are up-to-date and fit the requirements.

2. Make sure you have installed Vagrant from the source specified in installation guide. If you haven’t, remove all Vagrant related software and follow the guide.

3. Examine the common issues to see if you can find a match. Check the Seravo/wp-vagrant and Seravo/wordpress GitHub repositories to see if the issue has been already reported.

4. Complete a thorough Vagrant cleanup and test with an empty project.

   • Remove all Vagrant machines and plugins.
   • Clone the up-to-date template with git clone https://github.com/Seravo/wordpress.
   • Enable the beta box, run vagrant box update and remove the old boxes.
   • Start the machine with vagrant up. If the problem persists, consider reporting it.

Reporting an issue

After you’ve completed the debugging steps, you can either file a bug report or contact the Seravo customer service. If you need to include sensitive information with the report, the latter is recommended.

Include the following with your report to expedite the resolution of the problem:

• Operating system and version
• Vagrant version and VirtualBox version
• The output from vagrant up command.

Common issues

Windows: WordPress installation fails with symlink error

Issue:

Running vagrant up for the first time fails with an error symlink(): protocol error on Windows.

Fix:

Run Cygwin as an administrator when you are about to start a machine.

MacOS: /dev/vboxnetctl error during vagrant up

Issue:

Running vagrant up fails with an error failed to open /dev/vboxnetctl on macOS.

Fix:

Grant more permissions to VirtualBox via System Preferences > Security & Privacy > General. Finally, restart the VirtualBox service:

sudo /Library/Application\ Support/VirtualBox/LaunchDaemons/VirtualBoxStartup.sh restart
sudo /Library/StartupItems/VirtualBox/VirtualBox restart
sudo launchctl load /Library/LaunchDaemons/org.virtualbox.startup.plist

Linux: Errors related to creating host-only network adapters

Issue:

Running vagrant up fails with an error related to creating host-only network adapters on Linux.

Fix:

VirtualBox kernel modules might not be loaded. Run sudo vboxreload to reload the modules.

Linux: Networking issues or virtual interface errors

Issue:

Running vagrant up fails with an interface-related error, or networking fails. Known to affect Ubuntu 17.04 and later.

Fix:

Make sure ifconfig and route commands exist. On Ubuntu, install them with sudo apt-get install net-tools.

Linux: Ruby header files error during vagrant up

Issue:

Running vagrant up fails with an error mkmf.rb can't find header files. Known to affect Ubuntu 16.04 and later.

Fix:

Install the Ruby development files. On Ubuntu, run sudo apt-get install ruby-dev.

Developer documentation for Seravo.com – if you find flaws, please contribute a fix on GitHub!