Important Upgrade Notes


Support for Internet Explorer (IE11) is removed in Mattermost v5.16.0. See this forum post to learn more.

If you’re upgrading from a version earlier than… Then…
v5.21.0 Honour key value expiry in KVCompareAndSet, KVCompareAndDelete and KVList. We also improved handling of plugin key value race conditions and deleted keys in Postgres.
v5.20.0 Any pre-packaged plugin that is not enabled in the config.json will no longer install automatically, but can continue to be installed via the plugin marketplace.
Boolean elements from interactive dialogs are no longer serialized as strings. While we try to avoid breaking changes, this change was necessary to allow both the web and mobile apps to work with the boolean elements introduced with v5.16.
v5.19.0 LockTeammateNameDisplay setting was moved to Enterprise Edition E20 as it was erroneously available in Team Edition and Enterprise Edition E10.
v5.18.0 Marking a post unread from the mobile app requires v1.26 or later. If using v5.18, but mobile is on v1.25 or earlier, marking a post unread from webapp/desktop will only be reflected on mobile the next time the app launches or is brought to the foreground.
The Go module path of mattermost-server was changed to comply with the Go module version specification. Developers using Go modules with mattermost-server as a dependency must change the module and import paths to when upgrade this dependency to v5.18. See for further information.
Removed Team.InviteId from the related Websocket event and sanitized it on all team API endpoints for users without invite permissions.
Removed the ability to change the type of a channel using the PUT /channels/{channel_id} API endpoint. The new PUT /channels/{channel_id}/privacy endpoint should be used for that purpose.
v5.16.0 Support for Internet Explorer (IE11) is removed. See this forum post to learn more.
The Mattermost Desktop v4.3.0 release includes a change to how desktop notifications are sent from non-secure URLs (http://). Organizations using non-secure Mattermost Servers (http://) will need to update to Mattermost Server versions 5.16.0+, 5.15.1, 5.14.4 or 5.9.5 (ESR) to continue receiving desktop notifications when using Mattermost Desktop v4.3.0 or later.
When enabling Guest Accounts, all users who have the ability to invite users will be able to invite guests by default. System admins will need to remove this permission on each role via System Console > Permissions Schemes. In Mattermost Server version 5.17, the System admin will be the only role to automatically get the invite guest permission, however the fix will not be applicable in 5.16 due to database migration processes.
v5.14.0 Webhooks are now only displayed if the user is the creator of the webhook or a system administrator.
With the update from Google+ to Google People, system admins need to ensure the GoogleSettings.Scope config.json setting is set to profile email and UserAPIEndpoint setting should be set to,emailAddresses,nicknames,metadata per updated documentation.
v5.12.0 If your plugin uses the DeleteEphemeralMessage plugin API, update it to accept a postId string parameter. See documentation to learn more.
Image link and YouTube previews do not display unless System Console > Enable Link Previews is enabled. Please ensure that your Mattermost server is connected to the internet and has network access to the websites from which previews are expected to appear. Learn more here.
ExperimentalEnablePostMetadata setting was removed. Post metadata, including post dimensions, is now stored in the database to correct scroll position and eliminate scroll jumps as content loads in a channel.

If your integration uses Update.Props == nil to clear Props, this will no longer work in 5.11+. Instead, use Update.Props == {} to clear properties.

This change was made because Update.Props == nil unintentionally cleared all Props, such as the profile picture, instead of preserving them.

v5.10.0 SupportedTimezonesPath setting in config.json and changes to timezones in the UI based on the timezones.json file was removed. This was made to support storing configurations in the database.

If DisableLegacyMfa setting in config.json is set to true and multi-factor authentication is enabled, ensure your users have upgraded to mobile app version 1.17 or later. Otherwise, users who have MFA enabled may not be able to log in successfully.

If the setting is not defined in the config.json file, the DisableLegacyMfa setting is set to false by default to ensure no breaking changes.

We recommend setting DisableLegacyMfa to true for additional security hardening.

The public IP of the Mattermost application server is considered a reserved IP for additional security hardening in the context of untrusted external requests such as Open Graph metadata, webhooks or slash commands. See documentation for additional information.
v5.8.0 The local image proxy has been added, and images displayed within the client are now affected by the AllowUntrustedInternalConnections setting. See documentation for more details if you have trouble loading images.
v5.6.0 Built-in WebRTC is removed. See here for more details.

If EnablePublicChannelsMaterialization setting in config.json is set to false, an offline migration prior to upgrade may be required to synchronize the materialized table for public channels to increase channel search performance in the channel switcher (CTRL/CMD+K), channel autocomplete (~) and elsewhere in the UI. Use the following steps:

  1. Shut down your application servers.
  2. Connect to your Mattermost database.
  3. Execute the following queries:
DELETE FROM PublicChannels;
INSERT INTO PublicChannels
    (Id, DeleteAt, TeamId, DisplayName, Name, Header, Purpose)
    c.Id, c.DeleteAt, c.TeamId, c.DisplayName, c.Name, c.Header, c.Purpose
    Channels c
    c.Type = 'O';

The queries above rebuild the materialized PublicChannels table without modifying the authoritative Channels table.

Note that this migration is not required if the experimental PublicChannels feature was never disabled. This feature launched in Mattermost v5.4 with a temporary flag to disable should an issue arise, but nothing prompted doing so. If you did not modify this setting, there is no need to perform this migration.

v5.4.0 Mattermost mobile app version 1.13+ is required. File uploads will fail on earlier mobile app versions.
In certain upgrade scenarios the new Allow Team Administrators to edit others posts setting under General then Users and Teams may be set to True while the Mattermost default in 5.1 and earlier and with new 5.4+ installations is False.
v5.3.0 Those servers with Elasticsearch enabled will notice that hashtag search is case-sensitive.
v5.2.0 Those servers upgrading from v4.1 - v4.4 directly to v5.2 or later and have JIRA enabled will need to re-enable the JIRA plugin after an upgrade.
v5.1.0 mattermost export CLI command is renamed to mattermost export schedule. Make sure to update your scripts if you use this command.
v5.0.0 All API v3 endpoints are removed. See documentation to learn how to migrate your integrations to API v4.
platform binary is renamed to mattermost for a clearer install and upgrade experience. You should point your systemd service file at the new mattermost binary. All command line tools, including the bulk loading tool and developer tools, are also be renamed from platform to mattermost.
A Mattermost user setting to configure desktop notification duration in Account Settings > Notifications > Desktop Notifications is removed.
Slash commands configured to receive a GET request will have the payload being encoded in the query string instead of receiving it in the body of the request, consistent with standard HTTP requests. Although unlikely, this could break custom slash commands that use GET requests incorrectly.
A new config.json setting to whitelist types of protocols for auto-linking will be added. If you rely on custom protocols auto-linking in Mattermost, whitelist them in config.json before upgrading.
A new config.json setting to disable the permanent APIv4 delete team parameter is added. The setting will be off by default for all new and existing installs, except those deployed on GitLab Omnibus. If you reply on the APIv4 parameter, enable the setting in config.json before upgrading.
An unused ExtraUpdateAt field will be removed from the channel model.

This release includes support for post messages longer than the default of 4000 characters, but may require a manual database migration. This migration is entirely optional, and need only be done if you want to enable post messages up to 16383 characters. For many installations, no migration will be required, or the old limit remains sufficient.

To check your current post limit after upgrading to 5.0.0, look for a log message on startup:

[2018/03/27 09:08:00 EDT] [INFO] Post.Message supports at most 16383 characters (65535 bytes)

As of 5.0.0, the maximum post message size is 16383 (multi-byte) characters. If your logs show a number less than this limit and you want to enable longer post messages, you will need to manually migrate your database as described below. This migration can be slow for larger Posts tables, so it’s best to schedule this upgrade during off-peak hours.

To migrate a MySQL database, connect to your database and run the following:


To migrate a PostgreSQL database, connect to your database and run the following:


Restart your Mattermost instances.

Deployments on Enterprise E20 will need to enable RunJobs in the config.json and allow the permissions migration to complete before using Team Override Schemes.
v4.10.0 Old email invitation links will no longer work due to a bug fix where teams could be re-joined via the link. Team invite links copied from the Team Invite Link dialog, password reset links and email verification links are not affected and are still valid.
Server logs written to System Console > Logs and to the mattermost.log file specified in System Console > Logging > File Log Directory now use JSON formatting. If you have built a tool that parses the server logs and sends them to an external system, make sure it supports the JSON format.
Team icons with transparency will be filled with a white background in the Team Sidebar.
Those servers with SAML authentication enabled should upgrade during non-peak hours. SAML email addresses are migrated to lowercase to prevent login issues, which could result in longer than usual upgrade time.
If you use PostgreSQL database and the password contains special characters (e.g. []), escape them in your password, e.g., xxx[]xxx will be xxx%5B%5Dxxx.
v4.9.0 To improve the production use of Mattermost with Docker, the docker image is now running a as non-root user and listening on port 8000. Please read the upgrade instructions for important changes to existing installations.

Several configuration settings have been migrated to roles in the database and changing their config.json values no longer takes effect. These permissions can still be modified by their respective System Console settings as before. The affected config.json settings are:

RestrictPublicChannelManagement, RestrictPrivateChannelManagement, RestrictPublicChannelCreation, RestrictPrivateChannelCreation, RestrictPublicChannelDeletion, RestrictPrivateChannelDeletion, RestrictPrivateChannelManageMembers, EnableTeamCreation, EnableOnlyAdminIntegrations, RestrictPostDelete, AllowEditPost, RestrictTeamInvite, RestrictCustomEmojiCreation.

The behavior of the config.json setting PostEditTimeLimit has been updated to accomodate the migration to a roles based permission system. When post editing is permitted, set "PostEditTimeLimit": -1 to allow editing anytime, or set "PostEditTimeLimit" to a positive integer to restrict editing time in seconds. If post editing is disabled, this setting does not apply.

If using Let’s Encrypt without a proxy server, the server will fail to start with an error message unless the Forward80To443 config.json setting is set to true.

If forwarding port 80 to 443, the server will fail to start with an error message unless the ListenAddress config.json setting is set to listen on port 443.

v4.6.2 If using Let’s Encrypt without a proxy server, forward port 80 through a firewall, with the Forward80To443 config.json setting set to true to complete the Let’s Encrypt certification.
v4.4.0 Composite database indexes were added to the Posts table. This may lead to longer ugprade times for servers with more than 1 million messages.
LDAP sync now depends on email. Make sure all users on your AD/LDAP server have an email address or that their account is deactivated in Mattermost.
v4.2.0 Mattermost now handles multiple content types for integrations, including plaintext content type. If your integration suddenly prints the JSON payload data instead of rendering the generated message, make sure your integration is returning the application/json content-type to retain previous behavior.

By default, user-supplied URLs such as those used for Open Graph metadata, webhooks, or slash commands will no longer be allowed to connect to reserved IP addresses including loopback or link-local addresses used for internal networks.

This change may cause private integrations to break in testing environments, which may point to a URL such as

If you point private integrations to such URLs, you may whitelist such domains, IP addresses, or CIDR notations via the AllowedUntrustedInternalConnections config setting in your local environment. Although not recommended, you may also whitelist the addresses in your production environments. See documentation to learn more.

Push notification, OAuth 2.0 and WebRTC server URLs are trusted and not affected by this setting.

Uploaded file attachments are now grouped by day and stored in /data/<date-of-upload-as-YYYYMMDD>/teams/... of your file storage system.
Mattermost /platform repo has been separated to /mattermost-webapp and /mattermost-server. This may affect you if you have a private fork of the /platform repo. More details here.

(High Availability Only)

You must manually add new items to the ClusterSettings section of your existing config.json. See the Upgrading to Version 4.0 and Later section of High Availability Cluster (E20) for details.

v3.9.0 Old email invitation links, password reset links, and email verification links will no longer work due to a security change. Team invite links copied from the Team Invite Link dialog are not affected and are still valid.

A change is required in the proxy configuration. If you’re using NGINX:

  1. Open the NGINX configuration file as root. The file is usually /etc/nginx/sites-available/mattermost but might be different on your system.
  2. Locate the line: location /api/v3/users/websocket {
  3. Replace the line with location ~ /api/v[0-9]+/(users/)?websocket$ {

If you are using a proxy other than NGINX, make the equivalent change to that proxy’s configuration.

You need to verify settings in the System Console due to a security-related change.

  1. Go to the the GENERAL section of the System Console
  2. Click Logging
  3. Make sure that the File Log Directory field is either empty or has a directory path only.It must not have a filename as part of the path.
Backwards compatibility with the old CLI tool was removed. If you have any scripts that rely on the old CLI, they must be revised to use the new CLI.

Update the maximum number of files that can be open.

On RHEL6 and Ubuntu 14.04:
  • Verify that the line limit nofile 50000 50000 is included in the /etc/init/mattermost.conf file.
On RHEL7 and Ubuntu 16.04:
  • Verify that the line LimitNOFILE=49152 is included in the /etc/systemd/system/mattermost.service file.

(Enterprise Only)

Previous config.json values for restricting public and private channel management will be used as the default values for new settings for restricting private and public channel creation and deletion.

v3.4.0 If public links are enabled, existing public links will no longer be valid. This is because in earlier versions, existing public links were not invalidated when the Public Link Salt was regenerated. You must update any place where you have published these links.