Important Upgrade Notes


API version 3 is now removed. See to learn more.

If you’re upgrading from a version earlier than… Then…

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.