Before deleting a single folder, open teams.microsoft.com in a supported browser and sign in there. That one test decides everything that follows. If the browser session loads chats, calendar and calls normally, the account, the licence and the service are all working, and the fault is local to the desktop install. If the browser fails the same way, the desktop client is innocent and the problem sits in the account, the tenant or the network path.
The second thing to establish is which Teams client is installed, because the most repeated fix for this symptom — emptying %appdata%\Microsoft\Teams — is the path for the retired classic client. Microsoft publishes a different folder for the new one, and on macOS it publishes two.
Everything below is taken from Microsoft's own documentation. Where a widely circulated step has no first-party source, it is left out and named as left out at the end.
Split the Failure Before You Delete Anything
A client that hangs on the loading screen and a client that exits within seconds share a diagnostic path only up to the first fork. The browser test is that fork.
Microsoft lists the supported browsers for the Teams web client as Microsoft Edge, Chrome and Firefox at their latest three versions on Windows, macOS and Linux, and Safari at its latest two versions on macOS. A browser two years out of date is not a valid control for this test.
Run it in a normal window rather than a private one, signed in with the same work or school account. A healthy browser session sends you to the cache and install sections; a broken one sends you to the service and network sections.
Check the Service Before Blaming the Install
A tenant-wide incident produces exactly the symptom under discussion, and no amount of local repair will move it. Microsoft publishes two places to look, and which one applies depends on whether the account holds an admin role.
- Without admin rights:
status.cloud.microsoft. Microsoft describes this page as the option for people who cannot sign in to the admin center. The @MSFT365Status account on X carries notices for certain events as well. - With admin rights:
admin.microsoft.com, then Health > Service health, or the Service health card on the Home dashboard. Viewing it requires a role such as Service Support admin or Helpdesk admin.
The status wording is worth reading rather than skimming, because the labels carry different implications for how long the wait is likely to be. Investigating means a potential issue has been identified and scope is still being established. Service degradation is a confirmed issue with slow performance or intermittent interruptions. Service interruption means access is significantly impacted and the failure is reproducible and consistent. Extended recovery means corrective action is under way but will take time, and may involve a temporary fix.
If the dashboard shows an active incident for Teams, the correct action is to wait and to stop making local changes that will need undoing later.
The Cache Folder Moved When the Client Did
Microsoft's cache-clearing article gives four separate paths, split by client generation and operating system. Only one of them applies to any given machine.
The procedure on Windows for the new client is: right-click the Teams icon in the taskbar and select Quit, press Windows logo key + R, enter the path, select OK, delete every file and folder inside, then restart Teams. On macOS the same article uses Terminal, opened from /Applications/Utilities, after quitting Teams from the dock with Command-Q.
Two consequences are documented and worth expecting. First, the restart after clearing the cache may take longer than usual, because the cache has to be rebuilt — a slow first launch is not a failed fix. Second, there is a second supported route on Windows that is faster to describe and blunter in effect: Settings > Apps > Installed apps, search for Microsoft Teams, then More options (…) > Advanced options > Reset. Microsoft attaches an explicit warning to that button: app data will be deleted, including personalisation settings.
Neither route removes the account, and neither substitutes for the browser test: if the browser session is also broken, a local cache cannot be the cause.
A Classic Teams Client That Won't Start Is Behaving as Documented
Some machines are still carrying the old client, particularly in environments where an upgrade was deferred. For those, the failure is not a fault to be repaired. Microsoft's end-of-availability schedule is explicit:
| Milestone | Native Windows and macOS clients | VDI deployments |
| End of support | July 1, 2024 | October 1, 2024 |
| End of availability | July 1, 2025 | July 1, 2025 |
End of support meant no further updates, features or support. End of availability is the harder line: from July 1, 2025 the classic client is no longer available and no longer works, and users are shown a message stating that "Classic Teams is no longer available", pointing them to the web app or to their IT department for the new client. The same July 1, 2025 date applies to GCC, GCC High and DoD environments.
A classic client that opens to a dead window is therefore doing what it was scheduled to do. The fix is installation of the current client, not cache surgery, and the documented interim option is the web app.
Read the Sign-In Code Before Reaching for a Reset
When the client gets far enough to attempt authentication and then stops, it usually surfaces a hexadecimal code. Microsoft publishes a table of them, and several point somewhere other than Teams entirely.
Two entries in that table deserve emphasis because they are so frequently misread as client corruption:
- 0xCAA20003 — described as "You ran into an authorization problem." The published action is to make sure the date and time are set correctly, because incorrect date and time prevent connection to secure (https) sites. A device whose clock has drifted after a dead CMOS battery or a botched time-zone change produces this, and no reinstall will help.
- 0xCAA90018 — described as "You're not using the right credentials." Microsoft's explanation is that the Windows credentials signed in with are different from the Microsoft 365 credentials. This is routine on a personal machine where Windows is signed in with a consumer account and Teams is being asked for a work identity.
Two further entries are pure network: 0xCAA70007 ("The download has failed because the connection was interrupted") and 0xCAA82EE2 ("The request has timed out") both carry the same published action — confirm the internet connection, then work with IT to ensure other applications or a firewall configuration are not preventing access. 0xCAA20004 is the one that belongs to an administrator: the recommended action is to have IT confirm that the organisation complies with Microsoft Entra ID configuration policies.
A separate and unambiguous message is worth recognising on sight. "You're missing out! Ask your admin to enable Microsoft Teams for <CompanyName>" is documented as a tenant enablement problem, not a client one: in Microsoft 365 Education tenants Teams is not enabled by default and has to be activated by an administrator, and the same message appears where a Teams Exploratory experience has not been made available to the user.
When the Browser Loads Everything Except Teams
If the browser test failed, one documented cause is cookie policy rather than anything to do with the account. Microsoft's article for a Teams web client that does not load attributes it to trusted-sites and third-party cookie restrictions, and lists the exact domains that have to be permitted:
[*.]microsoft.com[*.]cloud.microsoft[*.]microsoftonline.com[*.]teams.skype.com[*.]teams.microsoft.com[*.]sfbassets.com[*.]skypeforbusiness.com
The entry points differ per browser. In Edge: Settings > Cookies and site permissions > Cookies and data stored > Manage and delete cookies and site data, where either Block third-party cookies is turned off or the domains above are added under Allow. In Chrome: Settings > Privacy and security > Cookies and other site data, then Add under Sites that can always use cookies, with Including third-party cookies on this site ticked. In Firefox: Settings > Privacy & Security > Manage Exceptions. In Safari, the step is to clear Prevent cross-site tracking under Preferences > Privacy and reopen the browser; Safari support is described as being in preview.
On a managed device these settings are frequently locked by policy, which is why Microsoft documents the same domain list as a group policy entry under Content settings > CookiesAllowedForUrls. If the toggles are greyed out, that is the answer, and the request goes to IT.
Installation That Fails or Reverts: Two Documented Causes
Where the client will not install, or reinstalls and breaks again, Microsoft names two specific conditions.
The first produces the message "Due to org policy, you can't install the new Teams. For more info, contact your IT admin." The documented cause is registry keys set by group policy or third-party tooling that block MSIX package installation — BlockNonAdminUserInstall, AllowAllTrustedApps and AllowDevelopmentWithoutDevLicense, under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock and HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\Appx. The corresponding policies sit in gpedit.msc under Computer Configuration > Administrative Templates > Windows Components > App package Deployment and should read Not configured. Microsoft also names the servicing updates that go with this fix: KB5031455 for Windows 11 and KB5031445 for Windows 10.
The second is narrower and easy to miss. On Windows 10, an install that ends in "We've run into an issue" is documented as a missing or outdated WebView2 Runtime; the published remedy is to download and install the runtime and then restart Teams. WebView2 is also listed as a standing prerequisite — "update to the most current version" — for both the Windows and macOS clients, which makes it a reasonable early check on any machine that renders a blank Teams window.
For a genuinely clean reinstall on Windows, Microsoft publishes the removal commands directly: Get-AppxPackage *MSTeams*|Remove-AppxPackage for a single user, Get-AppxPackage *MSTeams* -AllUsers |Remove-AppxPackage -AllUsers for all users, and teamsbootstrapper.exe -x -m for a machine-wide uninstall. Reinstallation uses the same bootstrapper: .\teamsbootstrapper.exe -p, or .\teamsbootstrapper.exe -p -o "c:\path\to\teams.msix" against a local copy of the package.
Requirements and Endpoints Worth Confirming Once
Underspecified hardware and blocked endpoints both produce launch failures that look like corruption, and both are published as fixed numbers.
| Requirement | Windows | macOS |
| Operating system | Windows 10 version 10.0.19041 or higher, excluding LTSC versions | One of the three most recent versions of macOS |
| Processor | 1.1 GHz or faster, two cores | Dual core |
| RAM | 4.0 GB | 4.0 GB |
| Free disk space | 3.0 GB | 1.5 GB |
| Display | 1024 x 768 or higher | 1200 x 800 or higher |
The LTSC exclusion is the one that catches people: a Windows 10 LTSC build is outside the supported set no matter how much memory the machine has.
On the network side, Microsoft's required-endpoint list for Teams covers teams.microsoft.com, *.teams.microsoft.com, teams.cloud.microsoft, *.teams.cloud.microsoft and *.lync.com, over TCP 443 and 80 plus UDP 443. Media traffic on the optimise category uses UDP 3478, 3479, 3480 and 3481. One firewall behaviour is called out specifically in the network preparation guidance: the firewall must not change the mapped NAT addresses or ports for UDP, and the WebSocket protocol should be allowed. Split-tunnel VPN configuration, so that Microsoft 365 traffic bypasses the tunnel, is the documented recommendation.
Stale clients are a related case. The desktop client is updated twice a month; on Windows it checks at startup and every few hours, downloads through Windows Delivery Optimization, and applies the update on restart, which can be forced with the Restart button next to the ellipsis. Microsoft notes that Delivery Optimization Download Mode 100 (Bypass) is not supported — an environment configured that way can leave clients pinned to an old build indefinitely. On Mac, updates arrive through Microsoft AutoUpdate, and Help > Check for updates opens it directly.
Collect the Logs Before Opening a Ticket
If nothing above has resolved it, the escalation path starts with logs, which Teams produces on demand:
- Windows: right-click the Teams icon in the system tray and choose Collect support files, or press Ctrl + Alt + Shift + 1.
- macOS: Help > Collect support files, or press Option + Command + Shift + 1.
Both sets land in the Downloads folder by default. Two details make the difference between a useful ticket and a slow one. Wait until the "Downloading web logs" banner has been dismissed before retrieving the files, or they will be incomplete. And note that timestamps inside the logs are recorded in UTC, so the time of the failure has to be converted before anyone can find it. Media and signalling logs are encrypted and readable only by Microsoft Support; the weblogs are plain text and can be opened locally.
What Is Not Claimed Here
Several steps that circulate widely for this symptom are absent above because no first-party source was found for them, and a plausible-sounding mechanism is not a verified one.
- No claim is made about what internal component is failing when the window renders blank. Microsoft documents the WebView2 dependency and documents cache locations; it does not publish a component-level explanation of a blank render, so none is offered here.
- No timing figure is given for how long a stuck loading screen should be tolerated before intervening. Microsoft publishes no such threshold.
- Deleting credential entries from Windows Credential Manager or the macOS keychain is a common recommendation. Microsoft's own sign-in error table does not list it as the action for any of the codes above, so it is not presented as a documented step.
- The registry value
SkipUpnPrefillis documented, but only for suppressing the pre-filled username on domain-joined PCs — not as a fix for a client that will not start.
When This Doesn't Apply
The sequence above assumes a work or school account on a client Microsoft still supports. Several situations fall outside it.
- Teams for personal use. The consumer client is a different product with its own requirements, and the enterprise service-health and Entra ID paths above do not apply to it.
- VDI and remote desktop environments. Citrix, VMware and Azure Virtual Desktop deployments have their own optimisation stack and their own end-of-support schedule for the classic client — October 1, 2024 rather than July 1, 2024. Cache deletion inside a non-persistent session may be reverted at logoff by design.
- Government clouds. GCC High and DoD tenants use separate endpoints and separate log designations, and guidance written against the worldwide service does not transfer cleanly.
- A machine that only fails during meetings. If Teams launches and signs in but audio, video or screen sharing fails, that is a media-path problem — the UDP 3478 to 3481 range and device permissions — and the startup diagnostics above will not find it.
- An active tenant incident. If the service health dashboard shows an interruption, every local step above is noise until the incident closes.
Where the browser test passes and the current client still refuses to start after a documented cache clear, a WebView2 update and a bootstrapper reinstall, the remaining work is administrative rather than technical: collect the support files, note the exact error code or message text, and hand both to whoever holds the Service Support admin role on the tenant.
Comments
Post a Comment