Skip to content

Commit da99595

Browse files
cormacpaynecormacpayne
authored
Merge pull request Azure#4937 from markcowl/docstrub
Adding module load troubleshooting doc to the repo
2 parents b21b4ce + 5c7e045 commit da99595

File tree

1 file changed

+140
-0
lines changed

1 file changed

+140
-0
lines changed

‎documentation/troubleshoot-module-load.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Troubleshooting Module Version Incompatibilities With Azure PowerShell
2+
3+
Azure PowerShell consists of multiple modules, each of which has a dependency on specific version of the central authentication module 'AzureRM.Profile'. If all versions of Azure PowerShell modules are kept up to date, and all are installed to the same scope, there should never be any incompatibility issues.
4+
5+
However, if some Azure PowerShell modules on a user's machine are updated while others or not, or if modules are installed to different scopes, or if an older version of the AzureRM.Profile module is imported in the current PowerShell session, then incompatibilities can occur. This document describes how to determine if there is a potential module incompatibility on a user machine, and how to resolve the incompatibility, including the following potential problems:
6+
7+
- [Prompt for Login when a cmdlet is executed after a previous login](#symptom-prompt-for-login-when-a-cmdlet-is-executed-after-a-previous-login)
8+
- [Error when loading an Azure PowerShell module](#symptom-error-when-importing-an-azure-powershell-module)
9+
10+
## Symptom: Prompt for Login When a Cmdlet is Executed After a Previous Login
11+
12+
After logging in, and executing a cmdlet, an error like the following is displayed, prompting for a second login:
13+
14+
```powershell
15+
PS C:\> Get-AzureRmResourceGroup
16+
Get-AzureRmResourceGroup : Run Login-AzureRmAccount to login.
17+
At line:1 char:1
18+
+ Get-AzureRmResourceGroup
19+
+ ~~~~~~~~~~~~~~~~~~~~~~~~
20+
+ CategoryInfo : CloseError: (:) [Get-AzureRmResourceGroup], PSInvalidOperationException
21+
+ FullyQualifiedErrorId : Microsoft.Azure.Commands.ResourceManager.Cmdlets.Implementation.GetAzureResourceGroupCmd
22+
let
23+
```
24+
25+
### Potential Reason 1: Older Version Stored in User or Global Scope
26+
27+
PowerShell allows installing multiple versions of modules. Normally, PowerShell will load the latest version of a module unless specifically instructed to load a specific version by using ```Import-Module -RequiredVersion <version>```. However, if modules are installed in multiple directories of the ```PSModulePath```, then the results can be unexpected. When PowerShell searches for a module in the module path, it will return the latest version stored in the earliest path component where the module appears, even if a later version of the module is installed in a subsequent directory in the PSModulePath.
28+
29+
For example, if the PSModulePath contains directory A followed by directory B, and if Directory A contains version 1 of a module, and Directory B contains version 2 of the module, PowerShell will *always* load version 1, unless the entire path to the later module in directory B is provided when importing the module.
30+
31+
To determine if this problem occurs on your machine, run ```Get-Module -ListAvailable``` and check for duplicate entries for AzureRM.Profile in different directories in the ```PSModulePath```. For example:
32+
33+
```powershell
34+
c:\> Get-Module -ListAvailable
35+
36+
Directory: C:\Users\UserName\Documents\WindowsPowerShell\Modules
37+
38+
39+
ModuleType Version Name ExportedCommands
40+
---------- ------- ---- ----------------
41+
Script 3.4.0 AzureRM.profile {Disable-AzureRmDataCollection, Disable-AzureRmContextAuto...
42+
43+
44+
Directory: C:\Program Files\WindowsPowerShell\Modules
45+
46+
47+
ModuleType Version Name ExportedCommands
48+
---------- ------- ---- ----------------
49+
Script 4.0.0 AzureRM.profile {Disable-AzureRmDataCollection, Disable-AzureRmContextAuto...
50+
51+
```
52+
53+
In this case, the earlier version of AzureRM.Profile (3.4.0) will *always* be loaded because the directory containing this version appears first in the module path. This means that newer versions of Azure PowerShell modules will be unable to use the authentication provided when logging in using the cmdlets from this module. IN other words, logging in using AzureRM.Profile version 3.4.0 will not provide authentication for modules that depend on a later version of AzureRM.Profile (like 3.4.1).
54+
55+
To resolve this problem, simply remove all versions of Azure PowerShell cmdlets not in the global scope ```%ProgramFiles%\WindowsPowerShell\Modules```. You can remove modules by physically removing the module directory (for example ```c:\users\<myuser>\Documents\WindowsPowerShell\Modules\AzureRM.Profile```).
56+
57+
### Potential Reason 2: Older / Newer version of Azure Module Installed
58+
59+
Additionally, because the Azure and AzureRM modules are installed separately, they are not always updated at the same time. If the 'Azure' module is updated without updating any installed AzureRM modules, then a version of AzureRM.profile that is compatible with the new 'Azure' module, but not compatible with the older 'AzureRM' modules may be loaded by default, and authentication will not work for AzureRM modules.
60+
61+
To detect this problem, run ```Get-Module -ListAvailable``` and look for multiple versions of ```Azure``` and ```AzureRm.Profile``` in the same directory in the module path, but fewer versions of other AzureRM Modules.
62+
63+
For example:
64+
65+
```
66+
PS C:\> Get-Module -ListAvailable
67+
68+
PS C:\Users\markcowl> get-module -ListAvailable
69+
70+
71+
Directory: C:\Program Files\WindowsPowerShell\Modules
72+
73+
74+
ModuleType Version Name ExportedCommands
75+
---------- ------- ---- ----------------
76+
Script 5.0.0 Azure {Add-AzureAccount, Set-AzureSubscription, New...
77+
Script 4.4.1 Azure {Add-AzureAccount, Set-AzureSubscription, New...
78+
Script 3.4.1 AzureRM.Compute {Remove-AzureRmAvailabilitySet, Get-AzureRmAvailabilitySet...
79+
Script 4.0.0 AzureRM.profile {Disable-AzureRmDataCollection, Disable-AzureRmContextAuto...
80+
Script 3.4.1 AzureRM.profile {Disable-AzureRmDataCollection, Disable-AzureRmContextAuto...
81+
```
82+
83+
As shown above, the 'Azure' module was updated without updating AzureRM.Compute, resulting in log in problems when using compute cmdlets.
84+
85+
To resolve the issues, update all AzureRM modules (for example ```Update-Module AzureRM.Compute```), or remove the later versions of 'Azure'.
86+
87+
Naturally, this problem can occur when any installed Azure PowerShell module is updated without updating others.
88+
89+
Note that this problem is permanently resolved staring with version 5.0.0 of Azure PowerShell. Any version of Azure PowerShell modules after this version my be independently updated without updating all installed Azure PowerShell modules.
90+
91+
## Symptom: Error when Importing an Azure PowerShell module
92+
93+
When importing an Azure PowerShell module into the current PowerShell Session, you see a message like the following:
94+
95+
```powershell
96+
PS C:\WINDOWS\system32> Import-Module AzureRM.Compute
97+
C:\Program Files\WindowsPowerShell\Modules\AzureRM.Compute\4.0.0\AzureRM.Compute.psm1 : This module requires
98+
AzureRM.Profile version 4.0.0. An earlier version of AzureRM.Profile is imported in the current PowerShell session. Please
99+
open a new session before importing this module. This error could indicate that multiple incompatible versions of the
100+
Azure PowerShell cmdlets are installed on your system. Please see aka.ms/azps-version-error for troubleshooting
101+
information.
102+
At line:1 char:1
103+
+ Import-Module AzureRM.Compute
104+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105+
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
106+
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,AzureRM.Compute.psm1
107+
108+
Import-Module : The module to process 'AzureRM.Compute.psm1', listed in field 'ModuleToProcess/RootModule' of module
109+
manifest 'C:\Program Files\WindowsPowerShell\Modules\AzureRM.Compute\4.0.0\AzureRM.Compute.psd1' was not processed
110+
because no valid module was found in any module directory.
111+
At line:1 char:1
112+
+ Import-Module AzureRM.Compute
113+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114+
+ CategoryInfo : ResourceUnavailable: (AzureRM.Compute:String) [Import-Module], PSInvalidOperationExcepti
115+
on
116+
+ FullyQualifiedErrorId : Modules_ModuleFileNotFound,Microsoft.PowerShell.Commands.ImportModuleCommand
117+
```
118+
119+
### Reason: Older Version of AzureRM.Profile Loaded in Session
120+
121+
If an existing PowerShell session has loaded a version of AzureRM.Profile, then that version cannot be replaced with an updated version. If you receive an error like the one mentioned above, you can determine if this is the issue by looking at the currently imported modules using ```Get-Module```:
122+
123+
```powershell
124+
PS C:\WINDOWS\system32> Get-Module
125+
126+
ModuleType Version Name ExportedCommands
127+
---------- ------- ---- ----------------
128+
Script 3.4.1 AzureRM.Profile {Add-AzureRmAccount, Add-AzureRmEnvironment, Clear-AzureRm...
129+
Manifest 3.1.0.0 Microsoft.PowerShell.Utility {Add-Member, Add-Type, Clear-Variable, Compare-Object...}
130+
Script 1.2 PSReadline {Get-PSReadlineKeyHandler, Get-PSReadlineOption, Remove-PS...
131+
132+
```
133+
134+
If you see a version of AzureRM.Profile installed in the session, you can resolve this issue, by ensuring that all AzureRM modules are up to date as shown [above](#potential-reason-1-older-version-stored-in-user-or-global-scope) and closing the PowerShell session.
135+
136+
## Why Are Incompatibilities Possible
137+
138+
Azure PowerShell is a set of binary modules, meaning that cmdlets are defined and implemented in .Net code. PowerShell loads cmdlet assemblies into a single AppDomain, and these assemblies cannot be unloaded, even if the module is removed. Therefore a module assembly and all its dependent assemblies remain loaded in the PowerShell session once it is imported until the PowerShell session is closed. Additionally, the types defined in a .Net assembly are strongly tied to the assembly version, so that the types from version A and version B of the same assembly will appear as different types in the PowerShell session. When these types are used in common by multiple assemblies (as in the authentication types in AzureRM.Profile), then the types that are meant to be common are actually different for each module version. This causes problems when authentication information is instantiated using types from version X of AzureRM.Profile, but an assembly requires version Y of these types.
139+
140+
This underlying problem is resolved in version 5.0 of AzureRM, as all authentication types used by the modules are assured to be fully backward compatible.

0 commit comments

Comments
 (0)