Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

Clearing the Teams cache on Windows: the steps Microsoft gives and the problems it says not to clear it for

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

Clearing the Teams cache is a targeted step for a small number of local client problems, not a general first move. Microsoft's page says plainly that it does not recommend it for missing messages, chat history not loading, a channel or team not appearing, or notifications and unread counts being wrong. In its words, clearing the cache "doesn't fix these issues but deletes the diagnostic logs that are needed to find the cause."

If the fault is one of those, leave the cache alone and keep the logs. If you have decided the local client really is the problem, the steps are below for both classic Teams and new Teams on Windows, with a copy taken first so the logs are not lost.

What the error means

There is no error code here. The page, "Clear the Teams client cache", is guidance on one action, and it applies to Classic Microsoft Teams and New Microsoft Teams. Its summary lists "the types of issues for which you shouldn't clear the Teams cache" and "the steps to delete the cache both in Teams for Windows and Teams for Mac when appropriate."

Microsoft's page gives two facts about what clearing does. First, it deletes the diagnostic logs. Second, the next start is slower: "The restart process after you clear the cache might take longer than usual because the Teams cache files have to be rebuilt."

Microsoft's page does not list which local client problems justify clearing the cache. It says only that you "can clear the Teams cache as a targeted step for a small number of problems with the local client" and that "it is not a general first step for all issues that you see in the Teams app." It does not say how to collect the diagnostic logs either, and the page names no registry, policy or service setting for the cache. So the decision has to come from your own checks showing that the fault sits on one PC and not in the account, the tenant or the service.

Likely causes

Microsoft's page names no root causes. The table below sorts the situations an administrator meets by what Microsoft's page says about clearing the cache.

The page splits the Windows steps into two products. For classic Teams the cache is the folder at %appdata%\Microsoft\Teams. For new Teams there are two methods: Reset in the Settings app, which deletes the app data, or deleting the files under the MSTeams_8wekyb3d8bbwe package folder. Check which product a user runs before you start, since Microsoft gives a different folder for each. Microsoft's page does not say how to tell the two apart on a PC, so ask the user which Teams window they use or look in Installed apps in Settings.

Cause What you see How to confirm
Messages, chat history, channels, teams, notifications or unread counts are wrong Missing messages, history not loading, a channel or team not appearing, wrong unread counts Compare with the same account in Teams on the web or on another PC; if it is wrong there too, the cache is not the cause, and Microsoft's page says not to clear it
A fault that exists only in one PC's Teams app The same account works elsewhere Test the same account on a second PC or in a browser
Teams is still running when you start Teams is open in the taskbar Quit Teams from the taskbar icon, as the page's first step says
You need the logs to find the cause Clearing the cache deletes the diagnostic logs Copy the folder before any deletion (below)

Prove the cause before changing anything

All of these are read-only.

  1. Sign in with the same account on another device or in a browser. If the problem follows the account, it is not a local cache fault.
  2. Check whether the symptom is one of the four Microsoft names: missing messages, chat history not loading, a channel or team not appearing, notifications and unread counts wrong. If it is, stop. Microsoft's page says not to clear the cache for them.
  3. Find out which Teams you run. Microsoft's page has separate steps for classic Teams and new Teams, and the folders differ.

Example (illustrative): at contoso.com.au, Aroha reports that a channel does not appear in Teams on ws07. The same channel shows for her on a phone and in the browser. That is a channel not appearing, which Microsoft's page lists as a problem not to clear the cache for, so the cache is left alone and the administrator looks at her account and membership instead. A different user, Daniel, has Teams that fails to start properly on one PC while the account works everywhere else. Only Daniel's case is a candidate for the steps below.

Fix

Work as the signed-in user whose Teams has the fault. Quit Teams first. Microsoft's page: "If Teams is still running, right-click the Teams icon on the taskbar, and then select Quit."

Classic Teams

Before you delete anything, copy the folder so the logs survive. Press the Windows logo key and R, enter this path in the Run dialog box and select OK:

%appdata%\Microsoft\Teams

Copy the whole Teams folder to a new folder that you name, for example teams-classic-before on the Desktop. Do not copy over an older copy.

Risk: the next steps delete every file and folder in the Classic Teams cache directory. Microsoft's page says this removes the diagnostic logs needed to find the cause of chat and channel faults, and the next start is slower while the cache is rebuilt.

  1. Open the same folder again with the Run dialog and the path above.
  2. Delete all files and folders in the directory.
  3. Restart Teams.

To undo it: quit Teams, then copy the contents of your teams-classic-before folder back into %appdata%\Microsoft\Teams, so the saved files are in the folder again, alongside anything Teams rebuilt. This restores the files, not the state the service had when they were written.

New Teams

Microsoft's page gives two methods. The first is Reset in Settings. Microsoft's page says "When you reset the Teams app, the app data is deleted. This data includes any personalization settings that you configured." Resetting deletes the data without saving it, and the page gives no way to restore it, so use the delete method below, where you hold a copy.

Quit Teams first: if it is still running, right-click the Teams icon on the taskbar and select Quit. Before you delete anything, copy the folder. Press the Windows logo key and R, enter this path in the Run dialog box and select OK:

%userprofile%\appdata\local\Packages\MSTeams_8wekyb3d8bbwe\LocalCache\Microsoft\MSTeams

Copy the whole MSTeams folder to a new folder that you name, for example teams-new-before on the Desktop.

Risk: the next steps delete every file and folder in the new Teams cache directory. Microsoft's page says this removes the diagnostic logs, and Teams takes longer to start while it rebuilds its files.

  1. If Teams is still running, right-click the Teams icon on the taskbar and select Quit.
  2. Open the same folder again with the Run dialog and the path above.
  3. Delete all files and folders in the directory.
  4. Restart Teams.

To undo it: quit Teams, then copy the contents of teams-new-before back into the MSTeams folder shown above.

Microsoft's page also has steps for Teams on a Mac.

Confirm the fix

  • Teams starts and signs in. Expect the first start to take longer than usual. Microsoft's page says the restart "might take longer than usual because the Teams cache files have to be rebuilt."
  • The original symptom is gone on that PC. If it is back, the cache was not the cause.
  • If the symptom was one of the four Microsoft says not to clear the cache for, it remains, and the logs you kept are the ones Microsoft's page says are needed to find the cause.

What to watch afterwards

  • The same symptom on the same PC after a few days of use. A return suggests a cause outside the local files.
  • The same user's Teams on another PC. If it also fails, the account or tenant is involved.
  • Disk space on the Desktop where you saved the copies. Delete a copy once the fault is closed, not before.

Risks and limits

These steps have not been run or lab-tested.

The steps use folder paths and File Explorer actions, not commands. The deletion cannot be undone from Teams, so the copy is the only way back. Microsoft's page names Classic Microsoft Teams and New Microsoft Teams and gives no later version range; it was last updated 2026-09-14, so check the current page before you rely on a path. The page does not say whether the same paths hold on a shared server or in a virtual desktop environment, so test on one user first. It does not explain how to collect diagnostic logs before a support case.

Sources