gh-emdashcodes-wp-ability-toolkit-claude-code-plugins-wp-env/skills/wp-env/references/troubleshooting.md

wp-env Troubleshooting Guide

Comprehensive troubleshooting for wp-env issues beyond the common errors covered in SKILL.md.

Troubleshooting Common Problems

Many common problems can be fixed by running through the following troubleshooting steps in order:

1. Check that wp-env is running

First, check that wp-env is running. One way to do this is to have Docker print a table with the currently running containers:

docker ps

In this table, by default, you should see three entries: wordpress with port 8888, tests-wordpress with port 8889 and mariadb with port 3306.

2. Check the port number

By default wp-env uses port 8888, meaning that the local environment will be available at http://localhost:8888.

You can configure the port that wp-env uses so that it doesn't clash with another server by specifying the WP_ENV_PORT environment variable when starting wp-env:

WP_ENV_PORT=3333 wp-env start

Running docker ps and inspecting the PORTS column allows you to determine which port wp-env is currently using.

You may also specify the port numbers in your .wp-env.json file, but the environment variables will take precedence.

3. Restart wp-env with updates

Restarting wp-env will restart the underlying Docker containers which can fix many issues.

To restart wp-env, just run wp-env start again. It will automatically stop and start the container. If you also pass the --update argument, it will download updates and configure WordPress again.

wp-env start --update

4. Restart Docker

Restarting Docker will restart the underlying Docker containers and volumes which can fix many issues.

To restart Docker:

1. Click on the Docker icon in the system tray or menu bar.
2. Select Restart.

Once restarted, start wp-env again:

wp-env start

5. Reset the database

Resetting the database which the local environment uses can fix many issues, especially when they are related to the WordPress installation.

To reset the database:

⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.

wp-env clean all
wp-env start

6. Destroy everything and start again 🔥

When all else fails, you can use wp-env destroy to forcibly remove all of the underlying Docker containers, volumes, and files. This will allow you to start from scratch.

To do so:

⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.

$ wp-env destroy
# This new instance is a fresh start with no existing data:
$ wp-env start