Troubleshooting InstantWP start up issues

Background

InstantWP is normally very stable and rock-solid. An InstantWP installation will run for months without any problems. The software underneath InstantWP (QEMU, Alpine Linux) is very similar to the software used by various cloud web hosting providers.

However, for various reasons you will sometimes get problems when InstantWP starts up. As InstantWP is completely portable, it relies on a set of background services to be available so that it will work. If these services are blocked or not started correctly, then you may need to troubleshoot your problem.

---

First Things to Do

The most important first thing is:

• DON'T PANIC: You just spent weeks working on a theme and now InstantWP won't start and you think you have lost all your work. This is very rare. Normally you can get InstantWP back up and running again.
• Take backups before any troubleshooting: As InstantWP is just a folder, take a copy of the InstantWP installation before troubleshooting, even if you think it is completely broken. It may save some tears later. Place it in a backup folder somewhere and leave it there.
• Take backups as you go: You should be backing up your code anyway as you make changes. There are dozens of backup plugins available. There is something for every budget, free or otherwise. You owe it to yourself to try a few and see what works for you. Most will work fine in InstantWP.
• Check your firewall and anti-virus (AV) software: InstantWP will launch various network services at startup and sometimes these will get blocked by over-zealous firewall and AV software. Try turning these off temporarily and see if InstantWP starts correctly again. If so, you may need to adjust the firewall / AV settings to allow InstantWP to work. Don't forget to turn the firewall and AV back on!

---

Specific Types of InstantWP Issues

Here are some things you can try for specific issues.

You downloaded InstantWP and it won't unzip

The downloaded file has possibly been corrupted during the download. This happens sometimes. Just download it again.

The InstantWP progress bar hangs

---

Specific InstantWP Troubleshooting Tips

The tips below will help fix problems.

Check that the web server is working using PHPInfo

Check that the web server is working using PHPInfo

If you wish to do a quick check that the web server is working correctly, you can check using the built-in PHP Info button on the Advanced Tab of the InstantWP Control Panel.

If this opens up and shows the PHP version, then the web server is working.

Stop InstantWP Running if it Hangs

On macOS

Start the Activity Monitor. Select any processes starting with 'instantwp' and click the Force Quit button on the menubar (the button with the X).

On Windows

Start the Task Manager (right click on the Task Bar and choose Task Manager). Go to the Details tab and choose any processes starting with 'instantwp'. Select these tasks and click the End Task button.

Show the QEMU window on startup

QEMU is the software that runs the Linux Virtual Machine (VM) is InstantWP. This is the server that actually runs WordPress. This tip is for when you need to see the Linux Virtual Machine booting to diagnose an issue.

On macOS

Change the ShowQEMUWindow setting in the config file to 'yes' and restart IWP.

On Windows

Open the Start-InstantWP.bat in a text editor (Notepad is fine). Edit the line

start /min bin\HideQEMUWindow.exe &

and add REM to the beginning to be

REM start /min bin\HideQEMUWindow.exe &

See the image below to see what this looks like:

This means Windows will ignore this line and the QEMU window will be shown.

Check the Database and Web Server using the QEMU Window

Once the QEMU window starts, you will see the various Linux services starting up.

You should be able to see that the database and web server have started up by looking at the services.

• The web server should have started correctly if the line 'starting apache2` is shown without errors.
• The database server should have started correctly if the line `starting mariadb' is shown without errors.

See the image below with these lines highlighted:

Check the Database and Web Server using the SSH Terminal

You can check to see if the database and web server are running by using the SSH Terminal by typing in some simple commands.

Start the SSH Terminal by using the SSH Terminal button on the Advanced Tab of the InstantWP Control Panel. See the image below:

To check the web server, do the following:

• Type the command sudo rc-service apache2 service and then hit enter.
• If the web server is running, it should say status: started.

To check the database server, do the following:

• Type the command sudo rc-service mariadb service and then hit enter.
• If the web server is running, it should say status: started.

Restart the Database or Web Server using the SSH Terminal

Start the SSH Terminal by using the SSH Terminal button on the Advanced Tab of the InstantWP Control Panel.

To restart the web server, do the following:

• Type the command sudo rc-service apache2 restart and then hit enter.
• The web server should restart without an error.

To restart the database server, do the following:

• Type the command sudo rc-service mariadb restart and then hit enter.
• The web server should restart without an error.