Troubleshooting
If issues are encountered when working with the VIP Local Development Environment, the first troubleshooting step should be verifying that the local machine is running up to date versions of VIP-CLI, Node.js, npm, and Docker.
Retrieve versions of VIP-CLI, Node.js, npm, and Docker with the command:
vip -v && node -v && npm -v && docker --version
Versions of VIP-CLI, Node.js, npm, and Docker on the local machine should always be kept up to date. Related errors can be indicators that a version update is needed.
VIP-CLI
- Symptom: Returned errors stating that a command is not valid may indicate that a version update is needed.
- Update: To the latest release version of VIP-CLI.
Node.js
- Update: To the latest active long-term support release of Node.js.
Docker
- Symptom:
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 . - Update: To version 4.13.1 or newer.
--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
Docker logs
The VIP Local Development Environment is composed of several docker containers. Reviewing the logs for individual containers can be useful for identifying if a single container is the cause of an issue. Logs for php-fpm
and traefik
containers often provide useful insights.
List all running containers for a local environment with the docker ps
command:
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 0a368d39d5fd phpmyadmin/phpmyadmin:5.1.1 "/lando-entrypoint.s…" 27 seconds ago Up 25 seconds 127.0.0.1:49161->80/tcp vipdevviplocal_phpmyadmin_1 14161140202c bitnami/elasticsearch:7.8.0 "/lando-entrypoint.s…" 27 seconds ago Up 25 seconds 9300/tcp, 127.0.0.1:49160->9200/tcp vipdevviplocal_vip-search_1 9c66c331852e wpvipdev/dev-tools:0.4 "/lando-entrypoint.s…" 27 seconds ago Up 25 seconds vipdevviplocal_devtools_1 33e29bc0f254 ghcr.io/automattic/vip-container-images/php-fpm:7.4 "/lando-entrypoint.s…" 27 seconds ago Up 25 seconds 9000/tcp vipdevviplocal_php_1
Container names output by the docker ps
command can be passed to the docker logs <name>
command to retrieve the logs for a specific container.
In this example command, logs are retrieved for the vipdevviplocal_php_1
container:
docker logs vipdevviplocal_php_1
The environment is 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.
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.
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
Last updated: November 04, 2022