Troubleshooting Connection Issues¶

If you are unable to connect to your remote machine using a PCoIP session, investigate the following possible causes.

Except where noted, the following checks apply to the remote macOS machine, and to the remote user account that will be accepting PCoIP connections.

Only one user can be logged in at a time¶

PCoIP connections will be denied if another user is already logged into the remote machine (for example, via the remote machine's user interface). This is true whether the logged-in user is using PCoIP or not. In order to ensure a remote user can log in, make sure all other users are logged out.

Make sure the remote user's name does not contain spaces¶

If your remote username contains spaces, the PCoIP agent will not be able to connect to it. You can either change the name to eliminate the space, or create a new account to use for PCoIP connections.

Confirm privacy permissions are correct¶

On the remote machine, log in using the account that will host PCoIP connections and check that the following permissions are granted on the remote machine:

1. Open System Preferences... > Security & Privacy, and select Accessibility from the list of options.

2. Under Allow the apps below to control your computer, confirm that PCoIP Agent appears in the list with a checkmark.

   If PCoIP Agent does not have a checkmark:

   1. Unlock the list of apps by clicking the lock icon in the bottom-left corner and providing your administrative credentials.

   2. Grant permission to the PCoIP Agent by clicking the checkbox beside PCoIP Agent.

3. Next, select Screen Recording from the list of options, and confirm that the PCoIP Agent appears in the list and has a checkmark beside it.

   If PCoIP Agent does not have a checkmark:

   1. Unlock the list of apps by clicking the lock icon in the bottom-left corner and providing your administrative credentials.

   2. Grant permission to the PCoIP Agent by clicking the checkbox beside PCoIP Agent.

Confirm that a restart was performed¶

The remote machine must be restarted after the PCoIP agent is installed. Until it is restarted, PCoIP connections will fail.

Confirm network conditions¶

The remote and client machines must be able to reach one another. For both machines, one of these conditions must be met:

• The firewall is off, or

• The firewall is on, and:

  • Automatically allow downloaded signed software to receive incoming connections is checked, or

  • On the remote machine, Automatically allow downloaded signed software to receive incoming connections is not checked, and the following executables are allowed through the firewall:

    • /Applications/PCoIP Agent.app
    • /Applications/PCoIP Agent.app/Contents/MacOS/pcoip-agent
    • /Applications/PCoIP Agent.app/Contents/MacOS/pcoip-server
    

  The Automatically allow downloaded signed software to receive incoming connections setting is in System Preferences > Security & Privacy, under the Firewall tab. Click Firewall Options to reveal it. The Firewall Options button is only visible if the firewall is on.

Check macOS login dialogs¶

Login prompts on the remote system will prevent a PCoIP session from starting. Make sure you have logged in to the remote computer using the user account that will host PCoIP sessions, and dismissed all prompts.

1. On the remote machine, log in to the user account that will host PCoIP sessions with either VNC or Screen Sharing.
2. From this connection, dismiss any login dialogs that are presented.
3. Attempt the PCoIP connection again, using the PCoIP Client.

Check for connected displays or display dongles¶

In some situations, connected displays or display dongles on the remote machine can prevent a PCoIP connection. This occurs because the real or simulated physical display interferes with the PCoIP agent's ability to create virtual displays for remoting.

Disconnecting removable displays and any display dongles from the remote machine may resolve this problem and allow a remote connection to be established.

Restart the PCoIP client¶

Quitting and re-launching the PCoIP client application may resolve connection issues.

Restart the remote machine¶

Rebooting the remote macOS system may resolve connection issues.

Reinstall the PCoIP Agent¶

In some situations, including after macOS updates, you may need to re-install the Graphics Agent for macOS to resolve connection issues.