docs/main/deployment-guide/desktop/desktop-troubleshooting.mdx
After upgrading to Mattermost Desktop v6.1.0 using the Windows MSI installer from an older release, the desktop or taskbar shortcut shows the wrong icon or fails to launch. This is due to a one-time icon handling change in the Windows MSI installer to improve shortcut reliability for future upgrades.
This issue doesn't block app usage and only affects Windows MSI installer upgrades from pre-v6.1.0 versions. Users can launch Mattermost from the Start Menu or a working desktop shortcut.Future upgrades to v6.1.1 and later will not require shortcut recreation.
To resolve this issue, recreate the shortcut:
The new shortcut will work correctly for all future upgrades.
Organizations standardizing on Windows installations can choose between Windows Store (recommended for automatic updates) or MSI packages (traditional deployment). The MSI method includes this one-time shortcut adjustment; the Windows Store method doesn't.
The location of the Mattermost desktop app configuration file depends on the platform where you're running Mattermost (and, in the case of macOS, how you've chosen to install the app):
Users\<username>\AppData\Roaming\Mattermost/Users/<username>/Library/Application Support/Mattermost/Users/<username>/Library/Containers/Mattermost.Desktop/Data/Library/Application Support/Mattermost (via Finder: ~/Library/Application Support/Mattermost as the extension is hidden)~/.config/MattermostIf you're not seeing in-app update notifications when new versions are available:
mattermost.com is allowed.EnableAutoUpdates Group Policy. Contact your IT department for clarification.From Mattermost server v11.6.0, system admins can set a minimum Desktop App version in System Console > Site Configuration > Customization > Minimum desktop app version. If your Desktop App version is below the configured minimum, you will see an update required screen and cannot access Mattermost until you update.
The screen includes a Download button that links to the apps download page configured by your admin. Select Download to go to that page, then follow the manual update steps for your platform.
If you believe your app is already up to date, contact your system admin to confirm the configured minimum version.
From v6.1.0, Mattermost Desktop updates are manual. Follow these steps for your platform:
macOS (App Store):
macOS (DMG installation):
Windows (Microsoft Store):
Windows (MSI installation):
Linux:
For AppImage users: Simply download the new AppImage file and replace the old one. Make sure to make it executable: chmod +x mattermost-desktop-*.AppImage
From Mattermost desktop v5.3, you can access logs via Help > Show logs, which opens the file manager window showing the location of the log file.
From Mattermost desktop v5.3, you can download a diagnostics text file via Help > Run diagnostics, which can be attached to a Support ticket.
If you experience deep links opening in the wrong workspace, ensure all relevant workspaces are pre-provisioned via the Group Policy DefaultServerList. See the multi-view and group policies documentation for details.
Verify the device is powerful enough to run several workspaces concurrently. Close unused tabs and pop-out windows to reduce load.
Check the desktop app advanced settings. Toggle Use GPU hardware acceleration off on systems with unstable drivers.
Mattermost desktop app configuration file. See the Where is configuration stored locally? section above for file location details.After installing v6.1.0 MSI, the old version still appears, both versions are present, or the upgrade doesn't seem to work. This is because you had a per-user installation from v5.9 to v6.0.4. From v6.1.0, the MSI installer defaults to per-machine (system-wide) installation. MSI installers cannot automatically upgrade across different installation contexts (per-user to per-machine).
To check your installation type before upgrading, open File Explorer.
C:\Program Files\Mattermost or C:\Program Files (x86)\Mattermost: Per-machine install (upgrade will work normally)C:\Users\<YourName>\AppData\Local\...: Per-user install (requires manual uninstall before v6.1.0)To resolve this issue, you must manually uninstall the old version before installing v6.1.0:
C:\Program Files\Mattermost).The app data might be corrupted. Remove all the files in %LOCALAPPDATA%\mattermost, then try reinstalling the app.
On macOS Catalina, this dialog can be triggered if the Mac Archive Utility is the default method for decompressing files. In this case using a third-party tool such as Keka or Unarchiver may resolve the problem.
- On Windows or Linux, select File > Settings and clear the Use GPU hardware acceleration option.
- On macOS, select Mattermost > Settings and clear the Use GPU hardware acceleration option.
%userprofile%\AppData\Roaming\Mattermost directory on your local machine.This issue can occur on Windows in a multiple-monitor setup. When you disconnect the monitor that Mattermost is displayed on, Mattermost continues to display at screen coordinates that no longer exist.
To resolve this issue, you can reset the desktop app screen location by deleting the screen location file. When the file is not present, the desktop app displays on the primary monitor by default.
To reset the desktop app screen location:
%APPDATA%\Mattermost folder.bounds-info.json.This issue can occur when localStorage has an unexpected state. To resolve the issue:
%APPDATA%\Mattermost folder, then delete the Local Storage folder.~/Library/Application Support/Mattermost folder, then delete the Local Storage folder.~/.config/Mattermost folder, then delete the Local Storage folder. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using rm -rf ~/.config/Mattermost.This issue can occur after a crash or unexpected shutdown of the desktop app that causes the app data to be corrupted. To resolve the issue:
%APPDATA%\Mattermost folder, then delete the IndexedDB folder and the Cookies and Cookies-journal files.~/Library/Application Support/Mattermost folder, then delete the IndexedDB folder and the Cookies and Cookies-journal files.~/.config/Mattermost folder, then delete the IndexedDB folder and the Cookies and Cookies-journal files. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using rm -rf ~/.config/Mattermost.Selecting Show Details on the dialog provides logs. Ways to resolve the issue:
Append Mattermost.exe; to the Registry Key HKLM\SYSTEM\CurrentControlSet\Services\CtxUvi\UviProcessExcludes and reboot the system.
For further assistance, review the Troubleshooting forum for previously reported errors, or join the Mattermost user community for troubleshooting help.
Yes. Run the following command from a terminal window: sudo snap remove mattermost-desktop.
When reporting issues found in the Mattermost desktop app, it's helpful to include the contents of the Developer Tools Console along with the information on this page.
To access the Developer Tools Console:
You can open an additional set of developer tools for each server you have added to the desktop app. The tools can be opened by pasting this command in the Developer Tools Console you opened with the steps described above:
javascriptdocument.getElementsByTagName("webview")[0].openDevTools();