Fix Connect-ExchangeOnline errors: module versions, MFA, WAM and proxies

Most Connect-ExchangeOnline failures today come from four places: an ExchangeOnlineManagement module that doesn't match the PowerShell version it runs in, the Web Account Manager (WAM) broker that became the default sign-in method in version 3.7.0, MFA and Conditional Access rejecting the sign-in, and network or account restrictions such as proxies and disabled PowerShell access. Identify which of the four you are hitting from the error text, apply the matching fix below, and keep -DisableWAM as a temporary workaround rather than the answer.

Who this is for and what you will have at the end

This guide is for Exchange Online administrators and automation owners whose Connect-ExchangeOnline command fails interactively, in a scheduled task or in a pipeline. By the end you will have:

• A module and PowerShell combination that Microsoft supports on your operating system.
• A working interactive connection with or without MFA, including device code sign-in on servers without a browser.
• Fixes for the documented WAM failures: RunAs sessions, GDAP partner connections and Task Scheduler jobs.
• A way to read Entra ID error codes from failed sign-ins.
• A short list of network and account checks for the remaining cases.

How a connection works now

Since October 2023, Exchange Online PowerShell and Security & Compliance PowerShell use REST API connections for every cmdlet. REST connections don't need Basic authentication in WinRM on your computer, don't build a remote PowerShell runspace, and retry transient failures automatically. The old remote PowerShell path is gone: the UseRPSSession switch is deprecated from version 3.9.2, and parameters that only worked with it, such as PSSessionOption, have no effect on REST connections.

Authentication is always modern authentication through Microsoft Entra ID. From version 3.7.0 on Windows, interactive sign-in goes through WAM by default. REST connections also depend on the PowerShellGet and PackageManagement modules on Windows.

That gives you a quick way to triage:

Prerequisites

• An account with the Exchange Online role needed for the cmdlets you plan to run. Connecting only requires that the account is allowed to use Exchange Online PowerShell; what you can do afterwards is controlled by role-based access control.
• Local administrator rights if you install the module for all users.
• Access to Microsoft Entra sign-in logs, or someone who has it, for Step 4.

Step 1: Get the module and PowerShell versions right

Check what is installed and where:

$PSVersionTable.PSVersion
Get-InstalledModule ExchangeOnlineManagement | Format-List Name,Version,InstalledLocation
Get-InstalledModule PackageManagement -AllVersions
Get-InstalledModule PowerShellGet -AllVersions

Compare the result with Microsoft's support matrix:

All module versions are supported in Windows PowerShell 5.1, which needs .NET Framework 4.7.2 or later. Two operating system details matter. On Windows 10, PowerShell 7.4 and later (and therefore module 3.5.0 and later in PowerShell 7) are supported only on the Enterprise and IoT LTSC editions still in support. On macOS and Linux, Connect-IPPSSession and Security & Compliance PowerShell aren't available in PowerShell 7, and Ubuntu 20.04 with modules 3.7.0 to 3.9.2 might fail with SSL protocol errors.

If PowerShell 7 is older than the module needs, update PowerShell rather than pinning an old module. If you must pin, install a specific version in the same scope you used originally:

Update-Module -Name ExchangeOnlineManagement -Scope CurrentUser
Install-Module -Name ExchangeOnlineManagement -RequiredVersion 3.9.2 -Scope CurrentUser

Installation errors

Files cannot be loaded because running scripts is disabled on this system. PowerShell isn't allowed to run scripts. From an elevated session run Set-ExecutionPolicy RemoteSigned.

The term 'Update-ModuleManifest' is not recognized or Cannot find a cmdlet Update-Manifest. PowerShellGet or PackageManagement is missing. Install or update PowerShellGet, close the window and reconnect. Preview versions of either module can also cause connection problems, so remove them if Get-InstalledModule -AllVersions shows any.

The specified module 'ExchangeOnlineManagement' with PowerShellGetFormatVersion '<version>' isn't supported by the current version of PowerShellGet or Unable to download the list of available providers. Update PowerShellGet, then reopen the window and retry. In Windows PowerShell 5.1 on older Windows versions, the PowerShell Gallery's TLS 1.2 requirement can cause the same symptoms.

No match was found for the specified search criteria and module name 'ExchangeOnlineManagement'. The PSGallery repository isn't registered. Run Register-PSRepository -Default.

Could not load file or assembly 'System.IdentityModel.Tokens.Jwt ...'. Another module loaded a conflicting assembly into the session. Open a new PowerShell window and connect to Exchange Online before importing other modules. Version 3.6.0 also fixed a compatibility issue with the Microsoft.Graph module, so update if you are older.

Step 2: Use the right sign-in method for the account

The basic interactive command works with or without MFA:

Connect-ExchangeOnline -UserPrincipalName admin@contoso.com
Get-ConnectionInformation
Get-AcceptedDomain

Get-ConnectionInformation replaces Get-PSSession for REST connections, and any working cmdlet such as Get-AcceptedDomain confirms the session. Other methods suit specific situations:

-Credential and -InlineCredential both fail for accounts that require MFA, which is now the normal case for admin accounts. Scripts that pass a PSCredential object should move to app-only authentication; Exchange Online PowerShell app-only auth with certificates walks through the setup.

Two more details from Microsoft's documentation are easy to miss. Connect and disconnect commands are likely to fail if the profile path of the signed-in Windows account contains special PowerShell characters such as $; use a different account. And from version 3.7.0, cmdlet help isn't downloaded by default, so add -LoadCmdletHelp if you need Get-Help to work for Exchange cmdlets.

Step 3: Fix WAM-related failures

From version 3.7.0, the module uses WAM as the default broker for user authentication on Windows. Microsoft documents three scenarios where that breaks.

RunAs and different user contexts

Running PowerShell as a different user from the one signed in to Windows fails with:

One or more errors occurred. (Unknown Status: Unexpected Error: 0xffffffff80070520 Context: A specified logon session does not exist. It may already have been terminated. Tag: 0x21420087 (error code -2147023584) ...

WAM needs the active user session to load its plug-ins and reach the keys and certificates in that user's profile. Microsoft's guidance is not to use RunAs for these commands; run PowerShell as the signed-in user. If you must connect from a different context temporarily, add -DisableWAM.

GDAP partner connections

With some Granular Delegated Admin Privileges flows, particularly with -DelegatedOrganization, WAM tokens miss the required role claims and you see:

The role assigned to user 'userx@tenantx.onmicrosoft.com' isn't supported in this scenario.

Disable WAM for that connection, and collect logs for Microsoft with -EnableErrorReporting:

Connect-ExchangeOnline -UserPrincipalName admin@contoso.com -DelegatedOrganization fabrikam.onmicrosoft.com -DisableWAM

Task Scheduler jobs

Scheduled tasks configured with Run whether user is logged on or not fail with the same logon session does not exist error, because WAM can't reach %LOCALAPPDATA%, keys or certificates without an active session. The supported fix is certificate-based authentication for anything unattended.

Other WAM symptoms

If you hit a WAM-related sign-in error that doesn't match the three documented scenarios, connect once with -DisableWAM to confirm WAM is the cause, then work on the underlying problem rather than leaving the switch in place. If Outlook and other Microsoft 365 apps on the same device also fail to sign in, check the Windows WAM plug-ins themselves with the steps in Stop Outlook asking for your password again and again.

-DisableWAM is available from version 3.7.2. Microsoft describes it as temporary and offers exo_wamissue@service.microsoft.com for cases that need WAM fixed rather than bypassed.

Step 4: Read MFA and Conditional Access errors

When Entra ID refuses to issue a token, the error includes an AADSTS code. Look the sign-in up in the Entra sign-in logs for the full reason and the policy involved.

Federated accounts have one extra constraint. If your identity provider or security token service isn't reachable from the internet, a federated account can't connect; Microsoft's guidance is to use a cloud-only account for Exchange Online PowerShell. For where Conditional Access fits in a wider access design, see the zero trust remote access architecture article.

Step 5: Check network, proxy and account access

Network and proxy

Microsoft's connection checklist notes that TCP port 80 traffic needs to be open between your computer and Microsoft 365, which is worth checking if your organization has a restrictive internet access policy. It also notes that on Linux you need module 3.0.0 or later to connect from behind a proxy server. Connect-ExchangeOnline has no proxy parameter for REST connections: PSSessionOption doesn't work in REST API connections and only ever applied together with the now-deprecated UseRPSSession switch.

Microsoft's module documentation doesn't describe a separate proxy setting, so the starting point is the platform default. PowerShell 7 runs on .NET, whose default HTTP proxy is read from the HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY environment variables. If those aren't set, Windows and macOS fall back to the user's or system's proxy settings, but on Linux .NET bypasses proxies entirely. On Linux build agents behind a proxy, set the variable for the session before connecting:

export HTTPS_PROXY=http://proxy.contoso.com:8080
pwsh -File ./Get-MailboxReport.ps1

Because the module also writes a temporary copy of itself to %TMP% during each connection, locked-down profiles can fail here too. From version 3.9.2, -EXOModuleBasePath lets you point that copy at a writable folder.

Account access to Exchange Online PowerShell

Every account can use Exchange Online PowerShell by default, but admins can turn it off per user. If one admin can't connect while others can, check:

Get-User -Identity admin@contoso.com | Format-List EXOModuleEnabled
Set-User -Identity admin@contoso.com -EXOModuleEnabled $true

Run the Set-User command from another admin account that can still connect and holds the Exchange Administrator role or membership of the Organization Management or Recipient Management role group. If a bulk command such as Get-User | Set-User -EXOModuleEnabled $false locked out every admin, Microsoft's guidance is to create a new admin account in the Microsoft 365 admin center and use it to restore access.

Sessions and memory

Disconnect when you finish with Disconnect-ExchangeOnline -Confirm:$false. Closing the window without disconnecting can use up the sessions available to you until they expire. Scripts that connect and disconnect repeatedly in one session can leak memory; connect once and use -CommandName to import only the cmdlets you need.

Verification

1. Get-ConnectionInformation returns a connection object with the expected tenant and user.
2. A read-only cmdlet such as Get-AcceptedDomain or Get-EXOMailbox -ResultSize 1 returns data.
3. The same command works in a fresh PowerShell window without -DisableWAM, or you have documented why WAM must stay off for that host.
4. The Entra sign-in log shows a successful interactive sign-in for the admin, with the Conditional Access policies you expect.

Troubleshooting summary and logging

When a failure doesn't match anything above, capture a log before opening a support case:

Connect-ExchangeOnline -UserPrincipalName admin@contoso.com -EnableErrorReporting -LogDirectoryPath C:\Temp\EXOLogs -LogLevel All

The global variable $EXO_LastExecutionStatus (version 3.3.0 and later) shows the status of the last cmdlet that ran, which is useful inside longer scripts. Cmdlets on REST connections also have a 15-minute timeout, so very large single operations, such as updating thousands of distribution group members in one call, can fail even though the connection itself is healthy; split them into smaller batches.

Checklist

• PowerShell version matches the module version; PowerShellGet and PackageManagement are current and not previews.
• Execution policy set to RemoteSigned where scripts run.
• Interactive admins use -UserPrincipalName or -Device; no stored passwords for MFA accounts.
• RunAs, GDAP and Task Scheduler WAM cases identified; -DisableWAM used only where documented and temporary.
• Unattended jobs moved to certificate or managed identity authentication.
• AADSTS codes checked in Entra sign-in logs against Conditional Access policies.
• Proxy environment variables set on Linux agents behind a proxy; temporary module path writable.
• EXOModuleEnabled is True for every admin who needs PowerShell.
• Sessions disconnected at the end of every script.

References

• About the Exchange Online PowerShell module
• Connect to Exchange Online PowerShell
• Connect-ExchangeOnline cmdlet reference
• Resolve issues in Exchange Online PowerShell module after WAM integration
• Enable or disable access to Exchange Online PowerShell
• Deprecation of Basic authentication in Exchange Online
• Microsoft Entra authentication and authorization error codes
• HttpClient.DefaultProxy property