Important Upgrade Notes

Available in Mattermost Free and Starter subscription plans. Available for Mattermost Self-Hosted deployments.

Important

  • Support for Mattermost Server v5.31 Extended Support Release has come to the end of its life cycle as of October 15, 2021. Upgrading to Mattermost Server v5.37 Extended Support Release or later is required.

  • The “version” CLI command will be deprecated in a future release.

  • Upgrading Mattermost can result in an error “ERROR: default for column “column_name” cannot be cast automatically to type jsonb” if you have non-JSON data in a column. This can also happen if the database data has been manipulated by external processes (e.g. plugins) and in cases where improper input data could get silently truncated due to varchar limits. The data in the affected database column has to be manually fixed.

If you’re upgrading from a version earlier than…

Then…

v6.1

Please refer to the schema migration analysis when upgrading to v6.1.

The Bleve index has been updated to use the scorch index type. This new default index type features some efficiency improvements which means that the indexes use significantly less disk space. To use this new type of index, after upgrading the server version, run a purge operation and then a reindex from the Bleve section of the System Console. Bleve is still compatible with the old indexes, so the currently indexed data will work fine if the purge and reindex is not run.

A composite index has been added to the jobs table for better query performance. For some customers with a large jobs table, this can take a long time, so we recommend adding the index during off-hours, and then running the migration. A table with more than 1 million rows can be considered as large enough to be updated prior to the upgrade.

  • For PostgreSQL: create index concurrently idx_jobs_status_type on jobs (status,type);

  • For MySQL: create index idx_jobs_status_type on Jobs (Status,Type);

v6.0

Longer migration times can be expected.

  • See this document for the estimated upgrade times with datasets of 10+ million posts.

  • See this document for the estimated upgrade times with datasets of 70+ million posts.

The field type of Data in model.ClusterMessage was changed to []byte from string. Therefore, a major thing to note is that a v6 server is incompatible to run along with a v5 server in a cluster. Customers upgrading from 5.x to 6.x cannot do a High Availability upgrade. While upgrading, it is required that no other v5 server runs when a v6 server is brought up. A v6 server will run significant database schema changes that can cause a large startup time depending on the dataset size. Zero downtime will not be possible, but depending on the efforts made during the migration process, it can be minimized to a large extent.

1. Low effort, long downtime - This is the usual process of starting a v6 server normally. This has two implications: during the migration process, various tables will be locked which will render those tables read-only during that period. Secondly, once the server finishes migration and starts the application, no other v5 server can run in the cluster.

2. Medium effort, medium downtime - This process will require SQL queries to be executed manually on the server. To avoid causing a table lock, a customer can choose to use the pt-online-schema-change tool for MySQL. For Postgres, the table locking is very minimal. The advantage is that since there are a lot of queries, the customer can take their own time to run individual queries during off-hours. All queries except #11 are safe to be executed this way. Then the usual method of (1) can be followed.

3. High effort, low downtime - This process requires everything of (2), plus it tries to minimize the impact of query #11. We can do this by following step 2, and then starting v6 along with a running v5 server, and then monitor the application logs. As soon as the v6 application starts up, we need to bring down a v5 node. This minimizes the downtime to only a few seconds.

It is recommended to start Mattermost directly and not through systemctl to avoid the server process getting killed during the migration. This can happen since the value of TimeoutStartSec in the provided systemctl service file is set to one hour.

Customers using the Mattermost Kubernetes operator should be aware of the above migration information and choose the path that is most appropriate for them. If (1) is acceptable, then the normal upgrade process using the operator will suffice. For minimum downtime, follow (2) before using the operator to update Mattermost following the normal upgrade process.

Please see the changelog for a list deprecations in this release.

Focalboard plugin has been renamed to Mattermost Boards, and v0.9.1 (released with Mattermost v6.0) is now enabled by default.

The advanced logging configuration schema changed. This is a breaking change relative to 5.x. See updated documentation.

The existing theme names and colors, including “Mattermost”, “Organization”, “Mattermost Dark”, and “Windows Dark” have been updated to the new “Denim”, “Quartz”, “Indigo”, and “Onyx” theme names and colors, respectively. Anyone using the existing themes will see slightly modified theme colors after their server or workspace is upgraded. The theme variables for the existing “Mattermost”, “Organization”, “Mattermost Dark”, and “Windows Dark” themes will still be accessible in our documentation, so a custom theme can be created with these theme variables if desired. Custom themes are unaffected by this change.

Some breaking changes to plugins are included:

  • Support for left-hand side-specific bot icons was dropped.

  • Removed a deprecated “Backend” field from the plugin manifest.

  • Converted the “Executables” field in the plugin manifest to a map.

v5.38.0

The “config watcher” (the mechanism that automatically reloads the config.json file) has been removed in favor of the mmctl config reload command, which must be run to apply configuration changes after they are made on disk. This change improves configuration performance and robustness.

v5.38 adds fixes for some of the incorrect mention counts and unreads around threads and channels since the introduction of Collapsed Reply Threads (Beta). This fix is done through a SQL migration, and it may take several minutes to complete for large databases. The fixCRTChannelMembershipCounts fix takes 1 minute and 20 seconds for a database containing approximately four million channel memberships and about 130,000 channels. The fixCRTThreadCountsAndUnreads fix takes about 3 minutes and 30 seconds for a database containing 56367 threads, 124587 thread memberships, and 220801 channel memberships. These are on MySQL v5.6.51.

Focalboard v0.8.2 (released with Mattermost v5.38.0) requires Mattermost v5.37+ due to the new database connection system.

v5.37.0

The platform binary and “–platform” flag have been removed. If you are using the “–platform” flag or are using the platform binary directly to run the Mattermost server application via a systemd file or custom script, you will be required to use only the mattermost binary.

Collapsed Reply Threads are available as beta in Mattermost Server v5.37 and later. It’s expected that you may experience bugs as we stabilize the feature. In particular, please be aware of the known issues documented here.

v5.37 adds support for emoji standard v13.0. If you have added a custom emoji in the past that uses one of the new system names, then it is going to get overwritten by the system emoji. The workaround is to change the custom emoji name.

Parts of Incident Collaboration are now available to all Mattermost editions. As part of this update, Incident Collaboration will require a minimum server version of v5.37. To learn more about what is available in each edition, visit our pricing page.

v5.36.0

Gossip clustering mode is now in General Availability and is no longer available as an option. All cluster traffic will always use the gossip protocol. The config setting UseExperimentalGossip has no effect and has only been kept for compatibility purposes. The setting to use gossip has been removed from the System Console. Note: For High Availability upgrades, all nodes in the cluster must use a single protocol. If an existing system is not currently using gossip, one node in a cluster can’t be upgraded while other nodes in the cluster use an older version. Customers must either use gossip for their High Availability upgrade, or customers must shut down all nodes, perform the upgrade, and then bring all nodes back up.

To enable Focalboard, open the Marketplace from the sidebar menu, install the Focalboard plugin, then click on Configure, enable it, and save. Update your NGINX or Apache web proxy config following these steps.

v5.35.0

Due to the introduction of backend database architecture required for upcoming new features, Shared Channels and Collapsed Reply Threads, the performance of the migration process for the v5.35 release (May 16, 2021) has been noticeably affected. Depending on the size, type, and version of the database, longer than usual upgrade times should be expected. This can vary from a couple of minutes (average case) to hours (worst case, MySQL 5.x only). A moderate to significant spike in database CPU usage should also be expected during this process. More details on the performance impact of the migration and possible mitigation strategies are provided here.

The existing password generation logic used during the bulk user import process was comparatively weak. Hence it’s advised for admins to immediately reset the passwords for all the users who were generated during the bulk import process and whose password has not been changed even once.

v5.35.0 introduces a new feature to search for files. Search results for files shared in the past may be incomplete until a content extraction command is executed to extract and index the content of files already in the database. Instances running Elasticsearch or Bleve search backends will also need to execute a Bulk Indexing after the content extraction is complete. Please see more details in this blog post.

v5.34.1

v5.34.1 fixes an issue where upgrading to v5.34.0 runs a migration that can cause timeouts on MySQL installations. Upgrading to v5.34.1 may also execute missing migrations that were scheduled for v5.32.0. These additions can be lengthy on very big MySQL (version 5.x) installations.

  • Altering of Posts.FileIds type (PostgreSQL only)

  • Added new column ThreadMemberships.UnreadMentions

  • Added new column Channels.Shared

  • Added new column Reactions.UpdateAt

  • Added new column Reactions.DeleteAt

v5.33.0

Deleting a reaction is now a soft delete in the Reactions table. A schema update is required and may take up to 15 seconds on first run with large data sets.

WebSocket handshakes done with HTTP version lower than 1.1 will result in a warning, and the server will transparently upgrade the version to 1.1 to comply with the WebSocket RFC. This is done to work around incorrect Nginx (and other proxy) configs that do not set the proxy_http_version directive to 1.1. This facility will be removed in a future Mattermost version and it is strongly recommended to fix the proxy configuration to correctly use the WebSocket protocol.

v5.32.0

ExperimentalChannelOrganization, EnableXToLeaveChannelsFromLHS, CloseUnusedDirectMessages, and ExperimentalHideTownSquareinLHS settings are only functional if the Legacy Sidebar (EnableLegacySidebar) is enabled since they are not compatible with the new sidebar experience. ExperimentalChannelSidebarOrganization has been deprecated, since the new sidebar is now enabled for all users.

Breaking changes to the Golang client API were introduced: GetPostThread, GetPostsForChannel, GetPostsSince, GetPostsAfter, GetPostsBefore, and GetPostsAroundLastUnread now require an additional collapsedThreads parameter to be passed. Any client making use of these functions will need to update them when upgrading its dependencies.

A breaking change was introduced when upgrading the Go version to v1.15.5 where user logins fail with AD/LDAP Sync when the certificate of the LDAP Server has no Subject Alternative Name (SAN) in it. Creating a new certificate on the AD/LDAP Server with the SAN inside fixes this.

TLS versions 1.0 and 1.1 have been deprecated by browser vendors. Starting in Mattermost Server v5.32 (February 16), mmctl returns an error when connected to Mattermost servers deployed with these TLS versions. System Admins will need to explicitly add a flag in their commands to continue to use them. We recommend upgrading to TLS version 1.2 or higher.

v5.31.0

For Mobile Apps v1.42.0+, the minimum server version is set to 5.31.3 as 5.31.3 fixed an issue where the server version was reported as v5.30.0.

v5.29.0

A new configuration setting ThreadAutoFollow has been added to support Collapsed Reply Threads releasing in beta in Q1 2021. This setting is enabled by default and may affect server performance. It is recommended to review our documentation on hardware requirements to ensure your servers are appropriately scaled for the size of your user base.

Disabled the xmlsec1-based SAML library in favor of the re-enabled and improved SAML library.

v5.28.0

Now when the service crashes, it will generate a coredump instead of just dumping the stack trace to the console. This allows us to preserve the full information of the crash to help with debugging it.

For more information about coredumps, please see: https://man7.org/linux/man-pages/man5/core.5.html.

In-product notices have been introduced to keep System Admins and end users informed of the latest product enhancements available in new server and desktop versions. Learn more about in-product notices and how to disable them in our documentation.

Disabled the xmlsec1-based SAML library in favor of the re-enabled and improved SAML library.

v5.27.0

Disabled the xmlsec1-based SAML library in favor of the re-enabled and improved SAML library.

v5.26.0

In v5.26, Elasticsearch indexes needed to be recreated. Admins should re-index Elasticsearch using the Purge index and then Index now button so that all the changes will be included in the index. Systems may be left with a limited search during the indexing, so it should be done during a time when there is little to no activity because it may take several hours.

An EnableExperimentalGossipEncryption option was added under ClusterSettings. If this is set to true, and UseExperimentalGossip is also true, all communication through the cluster using the gossip protocol will be encrypted. The encryption uses AES-256 by default, and it is not kept configurable by design. However, if one wishes, they can set the value in Systems table manually for the ClusterEncryptionKey row. A key is a byte array converted to base64. It should be either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.

To update the key, one can execute: UPDATE Systems SET Value='<value>' WHERE Name='ClusterEncryptionKey'; in MySQL and UPDATE systems SET value='<value>' WHERE name='ClusterEncryptionKey' for PostgreSQL.

For any change in this config setting to take effect, the whole cluster must be shut down first. Then the config change made, and then restarted. In a cluster, all servers either will completely use encryption or not. There cannot be any partial usage.

SAML Setting “Use Improved SAML Library (Beta)” was forcefully disabled. Follow instructions at https://docs.mattermost.com/deployment/sso-saml-before-you-begin.html for enabling SAML using the feature-equivalent xmlsec1 utility.

PostgreSQL ended long-term support for version 9.4 in February 2020. From v5.26 Mattermost officially supports PostgreSQL version 10 as PostgreSQL 9.4 is no longer supported. New installs will require PostgreSQL 10+. Previous Mattermost versions, including our current ESR, will continue to be compatible with PostgreSQL 9.4. PostgreSQL 9.4 and all 9.x versions are now fully deprecated in our v5.30 release (December 16, 2020). Please follow the instructions under the Upgrading Section within the PostgreSQL documentation.

v5.25.0

Some incorrect instructions regarding SAML setup with Active Directory ADFS for setting the “Relying Party Trust Identifier” were corrected. Although the settings will continue to work, it is encouraged that you modify those settings.

Disabled the xmlsec1-based SAML library in favor of the re-enabled and improved SAML library.

v5.24.0

A new configuration setting, ExtendSessionLengthWithActivity automatically extends sessions to keep users logged in if they are active in their Mattermost apps. It is recommended to enable this setting to improve user experience if compliant with your organization’s policies. Learn more here.

The mattermost_http_request_duration_seconds histogram metric (in Enterprise Edition) has been removed. This information was already captured by mattermost_api_time, which also contains the API handler name, HTTP method, and the response code.

As an example, if you are using rate(mattermost_http_request_duration_seconds_sum{server=~"$var"}[5m]) /   rate(mattermost_http_request_duration_seconds_count{server=~"$var"}[5m]) to measure average call duration, it needs to be replaced with sum(rate(mattermost_api_time_sum{server=~"$var"}[5m])) by (instance) /   sum(rate(mattermost_api_time_count{server=~"$var"}[5m])) by (instance).

Due to fixing performance issues related to emoji reactions, the performance of the upgrade has been affected in that the schema upgrade now takes more time in environments with lots of reactions in their database. These environments are recommended to perform the schema migration during low usage times and potentially in advance of the upgrade. Since this migration happens before the Mattermost server is fully launched, non-High Availability installs will be unreachable during this time.

The migration is a single line of SQL and can be applied directly to the database through the MySQL/PSQL command line clients if you prefer to decouple this from restarting the Mattermost server. It is fully backwards compatible so the schema change can be applied to any previous version of Mattermost without issue. During the time the schema change is running (~30s per million rows in the Reactions table), if end users attempt to react to posts, the emoji reactions will not load for end users.

MySQL: ALTER TABLE Reactions DROP PRIMARY KEY, ADD PRIMARY KEY (PostId, UserId, EmojiName);

PostgreSQL: ALTER TABLE reactions DROP CONSTRAINT reactions_pkey, ADD PRIMARY KEY (PostId, UserId, EmojiName);

On mobile apps, users will not be able to see LDAP group mentions (E20 feature) in the autocomplete dropdown. Users will still receive notifications if they are part of an LDAP group. However, the group mention keyword will not be highlighted.

SAML Setting “Use Improved SAML Library (Beta)” was forcefully disabled. Follow instructions at https://docs.mattermost.com/onboard/sso-saml.html for enabling SAML using the feature-equivalent xmlsec1 utility.

v5.22.0

Due to fixing performance issues related to emoji reactions, the performance of the upgrade has been affected in that the schema upgrade now takes more time in environments with lots of reactions in their database. These environments are recommended to perform the schema migration during low usage times and potentially in advance of the upgrade. Since this migration happens before the Mattermost server is fully launched, non-High Availability installs will be unreachable during this time.

The migration is a single line of SQL and can be applied directly to the database through the MySQL/PSQL command line clients if you prefer to decouple this from restarting the Mattermost server. It is fully backwards compatible so the schema change can be applied to any previous version of Mattermost without issue. During the time the schema change is running (~30s per million rows in the Reactions table), if end users attempt to react to posts, the emoji reactions will not load for end users.

MySQL: ALTER TABLE Reactions DROP PRIMARY KEY, ADD PRIMARY KEY (PostId, UserId, EmojiName);

Postgres: ALTER TABLE reactions DROP CONSTRAINT reactions_pkey, ADD PRIMARY KEY (PostId, UserId, EmojiName);

The Channel Moderation Settings feature is supported on mobile app versions v1.30 and later. In earlier versions of the mobile app, users who attempt to post or react to posts without proper permissions will see an error.

Direct access to the Props field in the model.Post structure has been deprecated. The available GetProps() and SetProps() methods should now be used. Also, direct copy of the model.Post structure must be avoided in favor of the provided Clone() method.

SAML Setting “Use Improved SAML Library (Beta)” was forcefully disabled. Follow instructions at https://docs.mattermost.com/onboard/sso-saml.html for enabling SAML using the feature-equivalent xmlsec1 utility.

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.

SAML Setting “Use Improved SAML Library (Beta)” was forcefully disabled. Follow instructions at https://docs.mattermost.com/onboard/sso-saml.html for enabling SAML using the feature-equivalent xmlsec1 utility.

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 github.com/mattermost/mattermost-server/v5 when upgrade this dependency to v5.18. See https://blog.golang.org/v2-go-modules 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 https://people.googleapis.com/v1/people/me?personFields=names,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.

Added the ability to enforce the administration of teams/channels with Group Sync. If Group Sync is enabled, all Team and Channel Admin designations will be lost upon upgrade. It is highly recommended that prior to upgrading, Team and Channel Admins are added to admin-specific LDAP groups corresponding to their teams and channels. After upgrading, those groups will need to be role-synced to the Team or Channel Admin role.

v5.11.0

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.

v5.9.0

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)
SELECT
    c.Id, c.DeleteAt, c.TeamId, c.DisplayName, c.Name, c.Header, c.Purpose
FROM
    Channels c
WHERE
    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 modal.

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:

ALTER TABLE Posts MODIFY COLUMN Message TEXT;

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

ALTER TABLE Posts ALTER COLUMN Message TYPE VARCHAR(65535);

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 accommodate 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 upgrade times for servers with more than one 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 http://127.0.0.1:1021/my-command.

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.

v4.0.0

(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 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.

v3.8.0

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.

v3.6.0

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 Public and Private 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.