Updating Rocket.Chat FAQ

This is a result of your MongoDB version not being compatible with the installed Rocket.Chat version.

It is advisable to incrementally upgrade the version of the deployed MongoDB to the supported version. See release engine compatibility for more information.

Unique ID is the unique identifier of a server. It's a hash created when the Rocket.Chat's deployment starts for the first time.

To prevent Unique ID duplication caused by deployment clones, splits, etc., when the database is copied to start a new deployment, the Unique ID record is also copied, and it becomes the same for the old and new deployments. Rocket.Chat implements a fingerprint solution to help admins identify when those cases happen by mistake.

The fingerprint is composed of the site URL setting and database connection string. When some parts of these two change, the fingerprint changes to a pending state. The admins are then requested to validate the fingerprint again by deciding if the change is, in fact, an expected update of the current workspace or a new workspace deployment.

Configuration update

If the change detected was expected to be a normal workspace configuration change, like a site URL change or a database string change, it's safe to confirm it. By confirming the update, nothing will change and the new fingerprint will become validated.

If the change is a new workspace, by confirming it as an update, it can generate issues with statistics reporting, license validation, push notifications, marketplace access, etc. since more than one workspace is accessing the cloud services using the same unique ID.

New workspace

If the change detected, in fact, means a new deployment has been done, by confirming a new workspace, all the identification information will be reset:

• Unique ID: A new unique hash will be generated.

• Cloud connection: All cloud connections will be reset.

• Cloud workspace: The cloud workspace data linking a cloud instance to the deployment will be reset.

• Cloud license: Any license provided by the cloud portal will be reset.

If the change is not a new workspace, confirming a new workspace can generate issues when connecting the deployment to the cloud workspace.

In some cases, for version 2.17.0 and above, you may need help with updating your app. If you click on the Install Update button and nothing happens for one minute, then you need to follow the steps below:

• Go to https://www.rocket.chat/download-apps.

• Download the matching edition to your OS.

• Install the app.

Before upgrading, make sure to create backups of your workspace data. You can also use virtual machines for testing purposes.

Most Rocket.Chat updates also update the database schema - the core layout. Now, theoretically, apart from adding oplogs to MongoDB for Rocket 1.x+, you should be able to merrily jump from version 0.62 through to 2.1.x. If you hit a problem aside from schema changes, it will be one of those.

The devs test changes from one version to another and maybe even over a few versions. But not every single version is up to the latest or, say 0.74.3 -> 1.3.2.That's where it may go wrong. So a recommended path is something like this:

-> 0.73.x -> 1.0.x -> 1.32 -> 2.0.x -> 2.1.x

Or possibly even more cautious:

-> 073.x - 1.0.x -> 1.1.x -> 1.2.x -> 1.3.x -> 2.0.x -> 2.1.x

Here, x means the last patched version, e.g. 1.3.2 Check tags or releases.

We have seen people make some big jumps. And some disasters too. If in doubt, take your time and do well to back up!

Backup is essential. Confirm the supported MongoDB version for the Rocket.Chat release you want to upgrade to and follow the official MongoDB documentation to upgrade it.

There are leaps between 2.x and 3.x. Then there are more leaps as you proceed through 3.x and then again to 4.x.