Debugging Teams Clients When Something Goes Wrong

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.

Tue Jun 26 2018 10:31:23 GMT+0100 (GMT Summer Time) <14808> -- info -- emit status indicator state change from NewActivity to NewActivity 
Tue Jun 26 2018 10:31:23 GMT+0100 (GMT Summer Time) <14808> -- info -- Setting the taskbar overlay icon - New activity 
Tue Jun 26 2018 10:31:23 GMT+0100 (GMT Summer Time) <14808> -- info -- Added NewActivity (current state: NewActivity -> NewActivity) 
Tue Jun 26 2018 10:33:22 GMT+0100 (GMT Summer Time) <14808> -- event -- isKeytarAsync: true, status: success, scenario: 1dffa265-4055-4795-965a-c0dc8e1eaabe, scenarioName: desktop_sso_save_ctx, name: desktop_sso_save_ctx, step: start, sequence: 0, delta: 0, scenarioDelta: 0, elapsed: 90489358, Scenario.Name: desktop_sso_save_ctx, Scenario.Step: start, Scenario.Status: success,  
Tue Jun 26 2018 10:33:22 GMT+0100 (GMT Summer Time) <14808> -- info -- ADAL: Tenant Id:c0a3a43f-9257-4949-be1b-f83cfb83f65f 
Tue Jun 26 2018 10:33:22 GMT+0100 (GMT Summer Time) <14808> -- info -- ADAL: Saving Context for:msteams_adalsso_c0a3a43f-9257-4949-be1b-f83cfb83f65f_adal_context 
Tue Jun 26 2018 10:33:22 GMT+0100 (GMT Summer Time) <14808> -- info -- ADAL: Tenant Id:c0a3a43f-9257-4949-be1b-f83cfb83f65f 
Tue Jun 26 2018 10:33:25 GMT+0100 (GMT Summer Time) <14808> -- event -- contextLength: 15, onQuit: undefined, status: success, scenario: 1dffa265-4055-4795-965a-c0dc8e1eaabe, scenarioName: desktop_sso_save_ctx, name: desktop_sso_save_ctx, step: stop, sequence: 1, delta: 3400, scenarioDelta: 3400, elapsed: 90492758, Scenario.Name: desktop_sso_save_ctx, Scenario.Step: stop, Scenario.Status: success,  

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.