SSH Gateway Issues

When using SSH Gateway on WP Engine there are some known limitations or access issues you may experience. In this article we’ll explain what limitations exist, why they happen, and how to best proceed without conflicts.

---

Not Seeing File Changes Immediately

File changes may take 5+ seconds to appear between the WordPress Admin Dashboard and your SSH session, and vice versa.

In this case, simply wait a few seconds and then you should see the changes appear. In some cases you may need to use an incognito window or refresh your browser cache to see changes faster.

Review our guide for purging caches.

---

Username Not Accepted

If you are receiving authentication errors when connecting, you will want to double check the format of your username. Your username must be formatted like so, where environment is replaced by your unique WP Engine environment name.

environment@environment.ssh.wpengine.net

1. Log in to the User Portal
2. Click on the environment name you wish to connect to
3. In the Overview section, locate SSH Login
4. Click the clipboard icon to copy the SSH login to your clipboard for easy pasting into your terminal

---

Region Not Accepted

Using a region and email address in your SSH login string is no longer necessary. If you are using a login string that includes a region like this…

'[email protected]+environment'@ssh.gcp-us-central1-farm-01.wpengine.io

…Then you should just use the updated method instead. This method automatically determines your region and looks like this:

environment@environment.ssh.wpengine.net

---

New Files Not Saved

Only files updated and saved within the /sites/environment/ directory will remain after the SSH session ends. A new SSH sandbox is created with each SSH session.

To avoid this issue please ensure any new files or directories are created within your /sites/environment/ directory, as this is the root directory of your WordPress site.

If you are creating scripts for use in SSH, please be sure these are placed in the _wpeprivate folder of your site, so these files will persist past the SSH session for future use.

---

Memory Limitations

If opening a new file or performing an action with WP-CLI requires too many server resources, it is possible the action or the session itself may be killed. Actions should be batched into smaller sets to ensure minimal resource consumption.

---

Lockouts

By default, your local machine will attempt to use all SSH keys present when connecting to your SSH Gateway. If 6 or more keys are presented unsuccessfully, the SSH Gateway will disconnect.

To avoid this issue, you should use an SSH config file to designate which key file should be used with which hostname.

---

Broken Connection

In some rare cases, it may be possible for software deploys to break existing connections. If this happens, simply reconnect after a few minutes to continue your work in SSH.

---

Permission denied (publickey)

When users are connecting to their SSH Gateway, there are two levels of authentication they pass through. The first determines whether the private and public keys match up and that the user has SSH access. If they do not, the user does not continue any further and receives the Permission denied (publickey) message.

1. Confirm your SSH key was added to the intended User Portal account
2. Confirm environment has SSH Gateway enabled
3. Confirm the SSH login is correctly typed
4. Do you have an SSH config file? This file should simply be named config and live in your ~/.ssh/ directory.
   • If you do, open it and ensure you have an entry in the SSH config file for *.wpengine.net mapped to the correct wpengine_rsa key file name and that everything is spelled correctly.
   • If you do not have an SSH config, set one up using this guide.

---

Connection Error Messages

You may see a number of other error messages depending on the error condition:

Error Message	Meaning
Cannot access environment [environment_name]	Either the environment you are trying to connect to does not exist (potentially mistyped), or the User Portal user your SSH key is assigned to does not have access to this particular environment
Install [environment_name] does not support ssh	The environment you are trying to connect to exists and you have access to it, but the environment is not on a server environment that supports SSH Gateway access
Install [environment_name] is disabled	The environment you are trying to connect to is disabled or inaccessible
Wrong gateway host. Use ssh.gcp-[region]-farm-01.wpengine.io instead	The environment you are trying to connect to exists and your user has access to it, but you have entered the wrong hostname. Use the suggested hostname in the error message instead.

---

NEXT STEP: SSH key management for SSH Gateway