Troubleshooting VIP-CLI

VIP-CLI commands may return errors or unexpected results for a variety of reasons. Common errors and issues, their causes, and recommended resolutions are described below.

If issues are encountered when working with VIP-CLI, the first troubleshooting step is to verify that the local machine is running up to date versions of VIP-CLI, Node.js, and npm.

1. Begin by retrieving versions of VIP-CLI, Node.js, and npm with the command:

vip -v && node -v && npm -v

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 running version of Node.js is the latest active long-term support release of Node.js.

The --debug option

If a VIP-CLI command produces unexpected results or reports an error that is not understandable, run the command again with the --debug (or -d) option. This adds verbose debugging details to the output as the command is processed. These details can help determine the point at which an error occurs, or add more context to the results returned in the response.

Resource restrictions

To maintain the integrity of site performance and services on VIP, commands that utilize excessive CPU, memory, or input/output (I/O) may be terminated. Review VIP’s recommendations for writing custom WP-CLI commands to optimize the performance of custom commands.

Applications missing from vip app list

To access an application via VIP-CLI, a user must have at least an App read role for that application. Check that the user has at least an App read role for the application(s) they expect to see. A user can review basic information about their roles & permissions at the User settings screen in the VIP Dashboard or via vip whoami command.

If a user does have an App read role or greater for the application they expect to see, but that application is not listed via vip app list, the user should try logging out and back in again to retry the command.

1. Run vip logout.
2. Run vip and follow the prompts to log in.
3. Run vip app list. If all of the expected applications are still not listed, contact VIP Support.

To run WP-CLI commands that modify an application’s database, a user must have at least an App write role for that application.

“Cancel received from server: Command canceled remotely”

The WP-CLI command was manually canceled by the user by selecting the “Cancel” option in the VIP Dashboard.

“Command cancelled”

The command was manually canceled by the user in the command line. At a prompt to confirm if the command should proceed, the user selected the equivalent of “no” or false.

“Command has been terminated”

The command was automatically terminated by WPVIP systems because it exceeded the resource limits. Custom WP-CLI commands that exceed resource limits should be improved by following guidelines to avoid memory exhaustion and database overload.

“Connection lost, retrying…”

If a user’s internet connection drops while a command is running, VIP-CLI will attempt to reconnect in the background. During this process, the “Connection lost, retrying…” message will be logged to the console. If the connection cannot be re-established in 1 minute, attempts to reconnect will discontinue and the terminal will be disconnected from the command.

“Error: [command] is not a valid subcommand.”

Verify that the VIP-CLI command used does not have spelling errors.

Run vip -h to confirm that the command used exists in the currently installed version of VIP-CLI. If the command does not appear in the output, update VIP-CLI to the latest version. The latest VIP features and subcommands are introduced in the most current versions of VIP-CLI.

“Error: Connection aborted.”

This error can be received when running WP-CLI commands with VIP-CLI and is caused by a pause in the connection between the user and VIP’s API. This affects only the command output seen in the terminal; it does not affect the execution of the running command. The command will continue running normally, and the user will automatically reconnect once the API is back online. The status of the command execution can also be viewed in the WP-CLI Commands panel in the VIP Dashboard.

“Error during Handshake”

This error can occur if stdin input is being manipulated through a shell utility such as xargs. For more information, refer to the Looping section of Advanced usage for VIP-CLI.

“Error: Rate limit exceeded: Please wait a moment and try again.”

VIP uses rate-limiting to reduce API abuse and charges to VIP’s APIs. This error indicates that too many requests are being sent to VIP’s servers either from the VIP Dashboard, VIP-CLI, or both.

To resolve this error:

• Close any non-used VIP Dashboard or VIP-CLI windows
• Reduce the number of concurrent commands running with VIP-CLI
• If a VIP-CLI command has not stopped correctly (especially if the command was killed using  Control + C, or equivalent) some remaining processes may still be running in the background. To stop these processes, quit the command line window completely.

Rate limit errors are between the end-user and VIP’s APIs. Though these errors appear in the VIP-CLI terminal window, they are not affecting the original output or logs of the command. Even if these errors occur, the VIP-CLI command is still running successfully.

“Maximum running command count has been reached for the site”

A maximum of four WP-CLI commands can run concurrently on a VIP production environment, and a maximum of two WP-CLI commands can run concurrently on non-production environments. Refer to the WP-CLI panel of the VIP Dashboard to review or cancel commands currently running on an environment.

“Received status code 401”

This error can be returned as part of a longer message in the terminal, for example:

Failed to fetch apps: Error: Network error: Response not successful: Received status code 401

To resolve this error:

1. Run vip logout.
2. Run vip and follow the prompts to log in again.

“The command is not permitted at this time”

A specific subset of core and other WP-CLI commands are disallowed for reasons of security, performance, and more. To view a full list of the commands that are available for use, run wp help.

Additional resources

For additional help with VIP-CLI or to report an issue, visit the VIP-CLI community on GitHub, or contact VIP Support by opening a support ticket.