Validate SSH alias configuration and provide clear error messages by Copilot · Pull Request #6204 · wp-cli/wp-cli

Copilot · 2026-01-22T18:09:44Z

When SSH aliases are misconfigured with ssh and path as separate keys (instead of embedding path in the SSH connection string), users receive cryptic foreach warnings and "Alias not found" errors.

# Misconfigured - triggers confusing errors
@staging:
  ssh: user@host
  path: /var/www/html

# Correct format
@staging:
  ssh: user@host:/var/www/html

Changes

Validation in Runner::set_alias(): Detect ssh + path combination and emit actionable error message
Defensive checks: Guard foreach loops in Runner::run_ssh_command(), Runner::set_alias(), and Configurator::get_aliases() to prevent warnings on malformed alias data
Test coverage: Added scenarios for common SSH alias misconfigurations

Error Message Improvement

Before:

PHP Warning: Invalid argument supplied for foreach() in phar://php/WP_CLI/Configurator.php on line 98
Error: Alias '@staging' not found.

After:

Error: Alias '@staging' is misconfigured. When 'ssh' is specified, 'path' should be included in the SSH connection string (e.g., 'user@host:/path/to/wordpress'), not as a separate key.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

366891.example.com
- Triggering command: /usr/bin/php /usr/bin/php /home/REDACTED/work/wp-cli/wp-cli/bin/../php/boot-fs.php core install-network --title=WP CLI Network --subdomains=1 is-installed bin/wp -v origin /home/REDACTED/wor@foo sh k/wp�� 29662' var_export( defiREDACTED bin/ssh li-test-core-dowcp /wp-content /usr/local/bin/m/tmp/wp-cli-test-core-install-cache-6.9/install_c4775ff9eceb34ebd92a3deef4bd8d0b--title=WP CLI Site bash (dns block)
c0ff8e.example.com
- Triggering command: /usr/bin/php /usr/bin/php /home/REDACTED/work/wp-cli/wp-cli/bin/../php/boot-fs.php core install-network --title=WP CLI Network --subdomains=1 ss-than-php-8&&~REDACTED vendor/bin/sh -ssh-alias-errorsh features/class-w/home/REDACTED/work/wp-cli/wp-cli/bin/wp (dns block)
example.com
- Triggering command: /usr/bin/php /usr/bin/php /home/REDACTED/work/wp-cli/wp-cli/bin/../php/boot-fs.php core install --url=REDACTED --title=WP CLI Site --admin_user=admin --admin_email=admin@example.com --admin_password=password1 --skip-email (dns block)
- Triggering command: /usr/bin/php /usr/bin/php /home/REDACTED/work/wp-cli/wp-cli/bin/../php/boot-fs.php core install --url=REDACTED --title=WP CLI Site --admin_user=admin --admin_email=admin@example.com --admin_password=password1 --skip-email eature er.feature rk.f�� ature 2>/dev/null bin/wp --local user.email vendor/bin/which uniq (dns block)
- Triggering command: /usr/bin/php /usr/bin/php /home/REDACTED/work/wp-cli/wp-cli/bin/../php/boot-fs.php core install --url=REDACTED --title=WP CLI Site --admin_user=admin --admin_email=admin@example.com --admin_password=password1 --skip-email rgo/bin/bash sh /hom�� -sqlite-integration-cache/sqlite-database-integration ssspidy <841956+swissspidy@users.noreply.github.com> (dns block)
host
- Triggering command: /usr/bin/ssh ssh -i identityfile.key -T -vvv user@host cd '/path/to/wordpress'; WP_CLI_RUNTIME_ALIAS='{"@foo":{"key":"identityfile.key"}}' wp @foo '--debug' '--version' ndor/bin/bash -v (dns block)
- Triggering command: /usr/bin/ssh ssh -i identityfile.key -T -vvv user@host cd '/path/to/wordpress'; WP_CLI_RUNTIME_ALIAS='{"@foo":{"key":"identityfile.key"}}' wp @foo '--debug' '--version' tnet/tools/mysql p mysql /home/REDACTED/.ca@foo sh bin/�� user create /home/REDACTED/.local/bin/sh submodules | heawp ABLE_WP_CRON', tcli ndor/bin/sh sh (dns block)
proxyhost
- Triggering command: /usr/bin/ssh ssh -vvv -W [host]:22 proxyhost behat -- cal/bin/php (dns block)
- Triggering command: /usr/bin/ssh ssh -vvv -W [host]:22 proxyhost core basename tnet/tools/which/tmp/wp-cli-test-core-download-cache-6.9/wp-login.php 00ee2423.4889147sh which /usr/local/bin/g@foo sh /hom�� -handling ) { define( 'DISABLE_WP_CRON', true ); } rgo/bin/sh ain..copilot/fixsh sh sh /usr/bin/php (dns block)
staging.example.com
- Triggering command: /usr/bin/ssh ssh -T -vvv deploy@staging.example.com cd '/var/www/staging'; wp '--debug' 'core' 'version' cli alias rgo/bin/sh /tmp/wp-cli-testrun-phpstan-tests /tmp/wp-cli-test-core-install-ca-c sh wp bin/�� --debug --version /bin/sh ation ost (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

This section details on the original issue you should resolve

<issue_title>Error message when misconfiguring SSH setting in alias is misleading</issue_title>
<issue_description>When you misconfigure the SSH setting in an alias, like omitting the path and adding a separate path: key instead, then the error message that WP-CLI provides is very misleading:
PHP Warning:  Invalid argument supplied for foreach() in phar://php/WP_CLI/Configurator.php on line 98
Error: Alias '@myalias' not found.
We should validate the settings and produce meaningful error messages that point to the actual issue instead.

Related: #5257</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Error message when misconfiguring SSH setting in alias is misleading #5279

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

…ray values Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

codecov · 2026-01-22T19:41:55Z

Codecov Report

❌ Patch coverage is 75.00000% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
php/WP_CLI/Runner.php	75.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

Initial plan

aa8c0a6

Copilot AI assigned Copilot and swissspidy Jan 22, 2026

Copilot started work on behalf of swissspidy January 22, 2026 18:10 View session

Copilot AI and others added 3 commits January 22, 2026 18:17

Add validation for misconfigured SSH aliases with separate path key

8322566

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Fix code style issues (trailing whitespace)

d5d70f5

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Add defensive check in get_aliases to prevent foreach error on non-ar…

c6085da

…ray values Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Fix misleading error message for misconfigured SSH alias settings~~ Validate SSH alias configuration and provide clear error messages Jan 22, 2026

Copilot AI requested a review from swissspidy January 22, 2026 18:22

Copilot finished work on behalf of swissspidy January 22, 2026 18:22

github-actions bot added bug command:cli Related to 'cli' command command:cli-utils labels Jan 22, 2026

swissspidy requested a review from Copilot January 22, 2026 19:55

Copilot started reviewing on behalf of swissspidy January 22, 2026 19:56 View session

This comment was marked as resolved.

Sign in to view

Remove redundant validation

39be029

swissspidy marked this pull request as ready for review January 22, 2026 23:02

swissspidy requested a review from a team as a code owner January 22, 2026 23:02

Merge branch 'main' into copilot/fix-ssh-alias-error-handling

f5d9c14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Validate SSH alias configuration and provide clear error messages#6204

Validate SSH alias configuration and provide clear error messages#6204
Copilot wants to merge 6 commits intomainfrom
copilot/fix-ssh-alias-error-handling

Copilot AI commented Jan 22, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Copilot AI commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Error Message Improvement

I tried to connect to the following addresses, but was blocked by firewall rules:

Comments on the Issue (you are @copilot in this section)

Uh oh!

codecov bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 22, 2026 •

edited

Loading

codecov bot commented Jan 22, 2026 •

edited

Loading