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:

vip -v && node -v && npm -v && docker --version

2. Confirm that the local machine is running the latest release version of VIP-CLI. 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 with the command: npm install -g @automattic/vip.
3. Confirm that the version of Docker is 4.13.1 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.
4. Confirm that the running version of Node.js is the latest active long-term support release of Node.js.

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

Accepted values: @automattic/vip:bin:dev-environment

Passing the --debug option with dev-env subcommands returns verbose debugging details to command output. 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.

For example:

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:

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:

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:

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:

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:

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 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”.

Resolve networking configuration issues

Wildcard DNS resolution is leveraged 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“.

Investigating 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:

;; 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

Resolving 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
• Windows
• Ubuntu

Investigating 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. 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.

$ 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: <https://test.vipdev.lndo.site/wp-json/>; 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 <https://wpvip.com>
< 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:

docker run -it --rm --network=host curl -v -o /dev/null test.vipdev.lndo.site

Resolving errors related to privileged port mapping

The following error may occur when starting a local environment on machines that are running Docker Desktop version 4.18 and greater:

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
 

Privileged port mapping is a required feature for the VIP Local Development Environment. To enable this feature and resolve the error, update settings in the Docker Desktop application:

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.