PowerShell Direct is a feature that allows you to log onto a Hyper-V host and establish a PowerShell session with a virtual machine, even if the virtual machine is not set up for remote management. It doesn’t even matter if there is no network path between the Hyper-V host and the virtual machine. You can still use PowerShell Direct to interact with the virtual machine.
Even though PowerShell Direct typically works exactly how it is supposed to, things can and sometimes do go wrong. As such, I wanted to give you a few pointers for troubleshooting PowerShell Direct.
Check the host operating system version
PowerShell Direct was introduced in Windows Server 2016. This means that if you have an older version of Windows Server (or a desktop version of Windows that is older than Windows 10), you won’t be able to use PowerShell Direct.
The easiest way to tell if your operating system is capable of supporting PowerShell Direct is to enter the following command:
$PSVersionTable.PSVersion
When you use this command, which you can see in the image below, there are two things that you should be looking for. First, check the Major version number. This number refers to the version of PowerShell that you are running. The system needs to be running PowerShell 5 or higher. The other thing that you will need to check is the build number, which must be 10240 or higher.
Basic PowerShell Direct error messages
Most of the time, the error messages produced by PowerShell Direct are intuitive enough that you can tell what is going on. You can see a couple of examples of this in the image below. The first error, for example, was triggered because I attempted to use PowerShell Direct to connect to a virtual machine that was not powered on. This error can also occur if the virtual machine is powered on but has not yet finished booting or if the virtual machine encounters an error that results in a boot failure.
I received the second error message shown in the image when I attempted to connect to a virtual machine that does not exist on the host. If you receive this error message (the input VMname parameter does not resolve to any virtual machine), make sure you spelled the virtual machine name correctly and that the virtual machine exists on the same host as your PowerShell session. If you are on the correct host and know that the virtual machine name is spelled correctly, make sure that you enter the virtual machine name and not the Windows hostname. These names usually differ from one another. Incidentally, you can also receive this error message if you lack the authority to manage Hyper-V virtual machines at the host level.
Invalid PowerShell Direct credentials
Another problem that is sometimes encountered when attempting to use PowerShell Direct is an error message indicating that your credentials are invalid. You can see an example of this in the next image.
If you receive this error message, then the first thing that you should do is obviously to make sure that you typed the right password. Remember, this is the virtual machine password and not the Hyper-V host password. If the credentials are correct, then it is possible that the account that you are using does not exist within the virtual machine. Let’s suppose, for example, that you are using a domain admin account to connect to a Hyper-V virtual machine using PowerShell Direct, but receive the error message indicating that your credentials are invalid. If this happens, it could be because the virtual machine is brand-new and has not yet been joined to the domain. It’s also possible that the Administrator account is not active on the virtual machine.
Other things to check
As it has matured, PowerShell Direct has gotten better at producing intuitive error messages. Even so, there are still situations in which you may see a generic error message. This is especially true if you happen to be running an old version of Windows, but there are circumstances that can cause generic errors is to appear even on the newer builds. The most common generic error message that I have run into states that “an error has occurred which Windows PowerShell cannot handle. A remote session might have ended.”
If you receive this error message, there are several things that you should check. One of the first things that I recommend taking a look at is the operating system running on the virtual machine you are trying to connect to. The virtual machine should be running Windows Server 2016 or higher or Windows 10. To the best of my knowledge, PowerShell Direct does not work with non-Windows guest operating systems.
Another thing to check is the virtual machine configuration version number. If you look at the next screenshot, you can see an excerpt from Hyper-V Manager. One of the pieces of information displayed alongside the virtual machines is the virtual machine configuration version number. Although it does not appear in the Microsoft documentation, some people have reported that the virtual machine version number has to be 7.1 or higher for PowerShell Direct to work. You can update a virtual machine’s version number by using the Update-VMVersion cmdlet, followed by the virtual machine name.
Finally, PowerShell Direct will be unable to connect to a virtual machine if it cannot access PowerShell within the guest operating system. This means if someone manages to disable PowerShell within a virtual machine, you will not be able to use PowerShell Direct to connect to that virtual machine.
Featured image: Shutterstock
