Petri Newsletter Sign-up
Office 365 Insider

Here at, we get IT — and so can you. Subscribe today to stay informed and knowledgeable regarding the latest on IT.

    See All Petri Newsletters

    Debugging Teams Clients When Something Goes Wrong

    Posted on by Tony Redmond in Microsoft Teams, Office, and Office 365

    Something went wrong with Teams

    Something Went Wrong with Teams

    When I use Teams, I switch between the iOS, browser, and desktop clients. The iOS client is a great mobile client. It performs well, switches between different Office 365 tenants snappily, and has a nice interface. I don’t do any Teams administration using the mobile client, and that’s where I use the Teams desktop client most.

    Like all software, the Teams desktop client has its moments. Both the full-blown Electron-based client and the new-fangled Windows S Hosted Web App (HWA – Microsoft’s version of a Progressive Web App, or PWA) encounter problems from time to time. The question is then how best to restore the client to good health.

    Sign Out of Teams

    Expired network credentials can be the root cause of failure to connects, failure for notifications to arrive, mysterious problems with message loading (Figure 1), and so on.

    Teams has a problem
    Figure 1: Teams runs into a problem (image credit: Tony Redmond)

    Teams keeps credentials in the Windows Credential Manager, but before you do anything else, take the easy way out and sign out of Teams and then sign back in. It’s amazing how many times this cures a problem.

    Stop Teams

    If a Teams desktop client becomes unresponsive, one way to attack the problem is to stop all Teams processes running on the workstation. Use Task Manager to find the Teams processes, select the top process, right click, and select End Task (Figure 2). Restart Teams and the problem has likely disappeared.

    Killing Teams client processes
    Figure 2: Killing Teams processes (image credit: Tony Redmond)

    Teams auto-updates desktop clients, so a problem encountered one week might be gone the next. But again, the nature of software is that sometimes problems do linger – especially edge conditions that are not easy to find in testing.

    Removing Browser Cookies

    If you experience issues connecting to Teams with the browser client, it’s often a good idea to try and connect with a private session. If that works, the problem might be linked to data cached by the browser. Often, these issues are cured by clearing the cookies used by Teams. Don’t hold back – select the cookies in use when Teams starts and remove them all (Figure 3).

    Remove Teams cookies
    Figure 3: Removing Teams cookies (image credit: Tony Redmond)

    Blowing Away the Teams Cache

    Those of us who grappled with Outlook connectivity problems in the past might remember the advice to blow away MAPI profiles or OST files when people experienced problems connecting to Exchange. MAPI profiles still do become corrupt, but much less now than in the past.

    The Teams desktop client equivalent of rebuilding an Outlook profile and a mailbox’s OST (offline store) is to blow away the Teams cache, which you’ll find at %\Appdata\Roaming\Microsoft\Teams (Figure 4).

    The Teams client cache
    Figure 4: The Teams cache (image credit: Tony Redmond)

    Removing cached information to cure problems is not uncommon. For example, here’s a Microsoft support article telling people how to delete the Office document cache. Removing the cache is the equivalent of a hard reset for Teams.

    Be sure to stop the Teams processes as described above before you remove the cache. When you restart Teams, the client detects that the cache is empty and will rebuild it, thus removing any lurking corruption that might be causing problems for the desktop client.

    Look at the Teams Log Files

    You might ask why it takes me so long to look at the Teams client log to search for clues about problems. Well, the reason is that the information written to the client log is a tad verbose (see extract below). In addition, the log records are for Teams developers to understand how the client functions rather than giving obvious clues when things go wrong.

    The client log is important though because if you run out of options and file a support request with Microsoft, it is likely that Microsoft will want to see the client log.

    To open the client log (logs.txt in the Teams cache), click the Teams icon in the system tray and then Get Logs from the menu. Notepad loads the file and you can browse it to your heart’s content before giving up and sending it to Microsoft.

    Diagnostic Log

    But wait, there’s more. The CTRL-Shift-Alt-1 key combination generates a diagnostic log file on Windows workstations, while Command + Option + Shift + 1 generates the file on a Mac. Teams creates the diagnostics log in the Downloads folder on the workstation and creates a name by combining MSTeams Diagnostics Log with the current timestamp.

    The diagnostics log is even more obtuse than the client log, but again, you probably won’t make much use of the file except to send it to Microsoft as part of a service request.

    Network Traces

    Microsoft might ask for a network trace to help resolve some support requests. I use Fiddler, but Charles Proxy is also valuable. In either case, make sure that you close all other applications that might generate network traffic before starting a trace and reproducing a problem. This will reduce the amount of data captured in the trace and make it easier for a developer to know what’s going on.

    Feedback to Microsoft

    Remember that if you hit a problem, you can send information to the Teams developers without filing a support request by clicking the Feedback button. You have the choice of giving a suggestion or reporting a problem. If you report a problem, Teams automatically attaches log files and you have the choice to include a screenshot of the current desktop (Figure 5).

    Teams feedback
    Figure 5: Giving Microsoft some feedback (image credit: Tony Redmond)

    You can also send feedback through the browser client, but you can’t include a screen snapshot with this client. The Feedback option is not available in mobile clients.

    Endlessly Seeking Perfection

    No one expects perfection, at least not in software. Teams is still relatively new and is adding lots of features at a rapid cadence. It’s unsurprising that things break in the Teams desktop client occasionally. As long as it stays that way, I’m OK with the situation. At least, I think I am.

    Follow Tony on Twitter @12Knocksinna.

    Want to know more about how to manage Office 365? Find what you need to know in “Office 365 for IT Pros”, the most comprehensive eBook covering all aspects of Office 365. Available in PDF and EPUB formats (suitable for iBooks) or for Amazon Kindle.



    Don't have a login but want to join the conversation? Sign up for a Petri Account