Title: Troubleshooting
Author: WordPress VIP Documentation
Published: April 29, 2022
Last modified: August 8, 2024
---
1. [VIP Local Development Environment](https://docs.wpvip.com/vip-local-development-environment/)
2. Troubleshooting
# Troubleshooting
If issues are encountered when working with the VIP Local Development Environment,
the first troubleshooting step is to verify that the local machine is running up
to date versions of VIP-CLI, Node.js, npm, and Docker.
1. Begin by retrieving versions of VIP-CLI, Node.js, npm, and Docker with the command:
```wp-block-preformatted
vip -v && node -v && npm -v && docker --version
```
2. **Confirm that the local machine is running [the latest release version of VIP-CLI](https://www.npmjs.com/package/@automattic/vip/v/latest).**
When running VIP-CLI commands, it is an indicator that a version update is needed
if errors are returned stating that a command is not valid. [Update VIP-CLI](https://docs.wpvip.com/vip-cli/installing-vip-cli/)
with the command: `npm install -g @automattic/vip`.
3. **Confirm that the version of Docker is [4.13.1](https://docs.docker.com/desktop/release-notes/#docker-desktop-4131)
or newer.** This error is an indicator that the version of Docker needs to be updated:`
Error: Failed to connect to docker. Please verify that the current user is part
of docker group and has access to docker commands.`This error often occurs due
to the removal of the `/var/run/docker.sock` symlink, introduced in [Docker 4.13.0](https://docs.docker.com/desktop/release-notes/#docker-desktop-4130).
4. **Confirm that the running version of Node.js is the [latest active long-term support release of Node.js](https://nodejs.org/en/about/previous-releases).**
## Restart the local machine
Some issues can also be resolved by restarting the user’s local machine. If an issue
persists after restarting the local machine, [retrieve verbose output with `--debug`](https://docs.wpvip.com/vip-local-development-environment/troubleshooting-dev-env/#h-retrieve-verbose-output-with-debug).
Create a VIP Support request with a detailed description of the issue and attached
the debugging output.
## Disable all other local development applications
Simultaneously running more than one type of local development environment application
can lead to unexpected results, including port conflicts. Any other local development
environment applications (e.g., Laravel or VVV) on a local machine should be shut
down before creating and running VIP Local Development Environments.
## Retrieve verbose output with `--debug`
Pass the `--debug` option with `dev-env` subcommands to return verbose debugging
details in the command output. The `--debug` option is built on [the debug npm package](https://www.npmjs.com/package/debug)
which accepts comma-delimited namespaces for generating debugging output for specific
events.
For example, passing the `--debug` option with the argument `@automattic/vip:bin:
dev-environment` will filter out extraneous details and return only debugging output
for the running `dev-env` subcommand.
```wp-block-preformatted
vip dev-env start --debug=@automattic/vip:bin:dev-environment
```
## Review service logs
The services running in a VIP Local Development Environment is composed of several
Docker containers. Reviewing the logs for individual services can be useful for
identifying if the service’s container is the cause of an issue.
VIP-CLI has a built-in convenience wrapper around Docker logs that enables logs
for all containers to be accessed for a local environment. In this command example,
logs for all running services can be accessed with the command:
```wp-block-preformatted
vip dev-env logs
```
This command example demonstrates how to access the logs for the Elasticsearch service.
The `--follow` argument is included in the command so that the log will continually
update in real time:
```wp-block-preformatted
vip dev-env logs --service=elasticsearch --follow --slug=example-site
```
## Debug an environment in a `DOWN` state
Information about a created local environment might show that the `STATUS` of the
environment is `DOWN`, even after running `vip dev-env start`. To investigate possible
causes for the environment to be in a `DOWN` state, run the `start` command again
with the argument `--debug=@automattic/vip:bin:dev-environment`.
For example:
```wp-block-preformatted
vip dev-env start --debug=@automattic/vip:bin:dev-environment
```
In the debugging output from the command in the terminal, locate a line that begins
with `DEBUG ==> scan results`. Services that failed to start will display `status
=false` in the scan results. Any services with `status=false` will cause the `STATUS`
of the environment to be `DOWN`.
Example debugging output for `DEBUG ==> scan results`:
```wp-block-preformatted
vip-local 13:32:45 DEBUG ==> scan results. url=http://vip-local.vipdev.lndo.site/, status=true, color=green, url=https://vip-local.vipdev.lndo.site/, status=true, color=green, url=http://*.vip-local.vipdev.lndo.site/, status=true, color=yellow, url=https://*.vip-local.vipdev.lndo.site/, status=true, color=yellow, url=http://localhost:55020, status=false, color=red, url=http://vip-local-pma.vipdev.lndo.site/, status=true, color=green
```
In the above output, `http://localhost:55020` has returned `status=false` and did
not pass reachability tests. Services that return `status=false` might have additional
messaging in the debugging output that can be helpful in determining the cause.
For example, searching for `http://localhost:55020` could return debugging output
similar to this:
```wp-block-preformatted
vip-local 13:32:40 DEBUG ==> checking to see if http://localhost:55020 is ready.
vip-local 13:32:40 DEBUG ==> scan failed for http://localhost:55020 code=ECONNREFUSED, message=connect ECONNREFUSED ::1:55020
vip-local 13:32:40 DEBUG ==> No response for http://localhost:55020. Setting to bad
vip-local 13:32:40 DEBUG ==> http://localhost:55020 not currently accessible
```
The above debug output indicates a possible [port binding](https://docs.wpvip.com/vip-local-development-environment/networking/#0-port-binding-for-services)
issue. Port binding issues can occur if the local machine is running another local
environment solution, or services such as Apache, NGINX, php-fpm, or MySQL. A local
environment will be unable to use a port if it is already occupied by a service
running elsewhere. Ports may also be blocked if the local machine has a proxy, tunneling,
or a security-related tool in place.
## Resolve error: `WordPress Core files not found`
One or both of the following errors might occur when creating or starting an environment
on a local machine running macOS:
* `WordPress Core files not found`
* PHP fatal error: `Failed opening required '/wp/config/wp-config.php'`
These errors often occur due to a race condition in mount availability. In some
cases the errors can be resolved by destroying and recreating the local environment.
If one or both errors persist, even after destroying and recreating the environment,
It is possible to resolve the errors by [updating the file sharing setting in the Docker Desktop application to “VirtioFS”](https://docs.docker.com/desktop/settings/mac/#general).
## Resolve networking configuration issues
[Wildcard DNS resolution is leveraged](https://docs.wpvip.com/vip-local-development-environment/networking/)
in order to point to localhost: `127.0.0.1`. It is possible for networking configurations
on the local machine to prevent the local environment’s requested domain from resolving
correctly.
### Symptoms
* The local environment is in a `DOWN` state.
* Attempts to load the local environment’s domain in a browser return the error
message “**This site can’t be reached**“.
### Investigate issues related to DNS
Verify that the domain resolution on the local machine is correct by querying the
DNS for the local environment’s domain. The command output should return an A Record
with the value `127.0.0.1`. For example:
```wp-block-preformatted
;; ANSWER SECTION:
test.vipdev.lndo.site. 3600 IN A 127.0.0.1
```
#### macOS
Use the `dig` command. For example: `dig test.vipdev.lndo.site`
#### Windows
Use the `nslookup` command. For example: `nslookup test.vipdev.lndo.site`
### Resolve DNS issues
If the returned A Record for the domain is blank, unexpected network settings are
preventing the local environment’s DNS from pointing to the IP address `127.0.0.1`.
To resolve this issue, DNS settings on the local machine can be updated to point
to a specific IPv4 address, such as Google’s DNS.
* [MacOS](https://developers.google.com/speed/public-dns/docs/using#macos)
* [Windows](https://developers.google.com/speed/public-dns/docs/using#windows)
* [Ubuntu](https://developers.google.com/speed/public-dns/docs/using#linux)
### Investigate issues related to proxies
It is possible for the DNS for a local environment’s domain to correctly point at
the localhost, but for proxies, tunneling, or security-related tools to prevent
traffic to that domain from resolving as expected.
To investigate, use the `curl` command to verify that an environment is reachable
and review the returned headers for more information about possible causes for the
issue. Include the `-v` switch in the `curl` command to return all headers in the
command output.
In this command example, the returned headers include the [`X-Powered-By: WordPress VIP` header](https://docs.wpvip.com/change-or-remove-http-headers-added-by-vip-go/).
The presence of this header indicates that traffic is correctly directed to the
local environment, and a network setting on the local machine or the machine’s ISP
is causing the DNS issue.
```wp-block-preformatted
$ curl -v -o /dev/null test.vipdev.lndo.site
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 127.0.0.1:80...
* TCP_NODELAY set
* Connected to test.vipdev.lndo.site (127.0.0.1) port 80 (#0)
> GET / HTTP/1.1
> Host: test.vipdev.lndo.site
> User-Agent: curl/7.68.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Type: text/html; charset=UTF-8
< Date: Tue, 17 May 2022 13:05:32 GMT
< Host-Header: a9130478a60e5f9135f765b23f26593b
< Link: ; rel="https://api.w.org/"
< Server: nginx/1.21.6
< X-Hacker: If you're reading this, you should visit wpvip.com/careers and apply to join the fun, mention this header.
< X-Powered-By: WordPress VIP
< X-Robots-Tag: noindex, nofollow
< Transfer-Encoding: chunked
<
{ [32589 bytes data]
100 80776 0 80776 0 0 355k 0 --:--:-- --:--:-- --:--:-- 355k
* Connection #0 to host test.vipdev.lndo.site left intact
```
A Docker version of the `curl` command can be used as an alternative. For example:
```wp-block-preformatted
docker run -it --rm --network=host curl -v -o /dev/null test.vipdev.lndo.site
```
### Resolve errors related to privileged port mapping
Privileged port mapping is a required feature for the VIP Local Development Environment.
Two errors are known to indicate issue related to privileged port mapping.
#### Error #1
```wp-block-preformatted
Error response from daemon: Ports are not available: exposing port TCP 127.0.0.1:443 -> 0.0.0.0:0: failed to connect to /var/run/com.docker.vmnetd.sock: is vmnetd running?: dial unix /var/run/com.docker.vmnetd.sock: connect: no such file or directory
```
#### Error #2
This error might occur when starting a local environment on a machine that is running
Docker Desktop version `4.18` and greater.
```wp-block-preformatted
Creating vip-dev-env-proxy_proxy_1 ... error
ERROR: for vip-dev-env-proxy_proxy_1 Cannot start service proxy: Ports are not available: exposing port TCP 127.0.0.1:443 -> 0.0.0.0:0: not allowed as current user.
You can enable privileged port mapping from Docker -> Settings... -> Advanced -> Enable privileged port mapping
```
#### Resolution
To enable privileged port mapping and resolve the errors, update settings in [the Docker Desktop application](https://www.docker.com/products/docker-desktop/):
1. Navigate to the “Settings” panel by selecting the gear icon in the upper right
of the Docker Desktop application.
2. Select “Advanced” from the navigation menu at the left.
3. Activate the “Enable privileged port mapping” feature option. **If this option
is already activated, it may be necessary to disable and then reenable the option
to resolve the issue.**
Last updated: August 08, 2024