---
title: Upgrade Unleash
description: "Migration guides and breaking changes for upgrading Unleash versions."
toc_max_heading_level: 2
---
import VideoContent from '@site/src/components/VideoContent.jsx'

This guide provides recommendations for upgrading your self-hosted Unleash instance, particularly when moving between major versions using Docker deployments.

Unleash aims to support client SDKs connecting to a server version that is one major version newer than the client, facilitating gradual upgrades.

Before you begin any major version upgrade, we strongly recommend performing a [full backup of your PostgreSQL database](/using-unleash/deploy/configuring-unleash#back-up-and-restore-the-database). This ensures you can restore your instance if issues occur during the upgrade.

## Upgrading from v6 to v7
Unleash v7, released in June 2025, introduced several key changes. Ensure you address the following before or during your upgrade to v7.

### ESM migration
Unleash v7 has fully migrated to ECMAScript Modules (ESM). If you run Unleash from source or using a custom build environment, ensure your environment supports ESM. This change may require updates to your custom scripts or integrations.

### Requires Node.js version 22+
If you run Unleash from source or using a custom build environment (not the official Docker image), you must ensure your environment uses Node.js version 22 or later. Unleash v7 drops support for Node.js versions below 22, which is [active LTS at the time of release](https://github.com/nodejs/Release/blob/cf57a9739438f7a46d8f49b18aa8c2de3f3ca756/README.md#release-schedule).

### Database requirement: PostgreSQL v14+
Unleash v7 requires **PostgreSQL version 14 or later**. Running v7 with older PostgreSQL versions (10, 11, 12, 13) is unsupported, though the server might start with a warning message.

### API changes

As part of our commitment to maintaining a clean and robust codebase, several deprecated API endpoints and schema properties have been removed in Unleash v7.

<details>
  <summary>Removed API endpoints</summary>

- **GET `/api/admin/archive/features`**
  
  Deprecated in: v4.10.0, use `/api/admin/search/features?archived=IS:true` instead.

  ---

- **GET `/api/admin/archive/features/{projectId}`**

  Deprecated in: v4.11.0, use `/api/admin/search/features?project=IS:{projectId}&archived=IS:true` instead.

  ---

- **GET `/api/admin/projects/{projectId}/users`**

  Deprecated in: v4.14.3, use `/api/admin/projects/{projectId}/access` instead.

  ---

- **GET, PATCH, and PUT `/api/admin/projects/{projectId}/features/{featureName}/variants`**

  Deprecated in: v4.21.0, use [strategy variants](https://docs.getunleash.io/reference/strategy-variants) instead.
  You can create or update variants when creating or adding a strategy to a feature flag.
  For example: `/api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies`.

  ---

- **POST `/api/admin/projects/{projectId}/role/{roleId}/access`**
  
  Deprecated in: v5.5.0, use `/api/admin/projects/{projectId}/access` instead.

  ---

- **PUT and DELETE `/api/admin/projects/{projectId}/groups/{groupId}/roles/{roleId}`**

  Deprecated in: v5.5.0, use `/api/admin/projects/{projectId}/groups/{groupId}/roles` instead.

  ---

- **PUT, POST, and DELETE `/api/admin/projects/{projectId}/users/{userId}/roles/{roleId}`**

  Deprecated in: v5.5.0, use `/api/admin/projects/{projectId}/users/{userId}/roles` instead.

  ---

- **GET `/api/admin/projects/{projectId}`**
  
  Deprecated in: v5.8.0, use `/api/admin/projects/{projectId}/overview` instead.

  ---

- **GET `/api/admin/dashboard/executive`**
  
  Deprecated in: v5.11.0, use `/api/admin/projects/{projectId}/overview` instead.

  ---

- **POST `/api/admin/events/search`**
  
  Deprecated in: v6.1.0, use `/api/admin/search/events` instead.

  ---

- **GET `/api/admin/metrics/traffic/{period}`**

  Deprecated in: v6.8.0, use `/api/admin/metrics/traffic` instead.

  ---

- **POST `/api/admin/ui-config`**

  Deprecated in: v6.9.0, use `/api/admin/ui-config/cors` instead.

</details>

<details>
  <summary>Removed schema properties</summary>

- **`username`**
  
  Removed from `apiTokenSchema` and `createApiTokenSchema`.
  Deprecated in: v5.1.0 and v5.3.0
  Affected endpoints: `/api/admin/api-tokens`, `/api/admin/api-tokens/{name}`, and `/api/admin/projects/{projectId}/api-tokens`.

  ---

- **`environment`**

  Removed from `sdkContextSchema`, `clientApplicationSchema`, `clientMetricsSchema`, and `clientFeaturesQuerySchema`.
  Deprecated in: v5.2.0
  Affected endpoints: Client API and Playground endpoints. Environment is now part of the API token.

  ---

- **`isAPI`** 

  Removed from `userSchema`.
  Deprecated in: v5.3.0
  Affected endpoints: `/api/admin/user`, `/api/admin/user-admin`, `/api/admin/user-admin/access`, `/api/admin/user-admin/search`, `/api/admin/user-admin/{id}`, `/api/admin/access/overview`,
 `/api/admin/projects/{projectId}/access`, `/api/admin/groups`, `/api/admin/groups/{groupId}`, `/api/admin/invite-link/tokens`, `/api/admin/user-admin/{id}/permissions`, `/auth/simple/login`,
  `api/admin/projects/{projectId}/access`, `/invite/{token}/signup`.

</details>

<details>
  <summary>Previously deprecated endpoints restored in v7</summary>
  - **GET `/api/admin/instance-admin/statistics`**

  Deprecated in 4.17.0 - This was accidental and it has now been fully restored.

  ---

- **POST `/api/admin/strategies`**

  Deprecated in v6.0.0 but, due to user feedback, it has been reintroduced in v7.0.0. It can be used to create custom strategies.
</details>

## Upgrading from v5 to v6

[Unleash v6](https://github.com/Unleash/unleash/issues/4380), released in June 2024, introduced several key changes. Ensure you address the following before or during your upgrade to v6.

### Database requirement: PostgreSQL v13+

Unleash v6 requires **PostgreSQL version 13 or later**. Running v6 with older PostgreSQL versions (10, 11, 12) is unsupported, though the server might start with a warning message.
Plan to upgrade your PostgreSQL instance to a supported version before or alongside your Unleash upgrade.

### License key required for self-hosted Enterprise

Starting with v6, self-hosted Unleash Enterprise instances require a valid license key to function. Obtain your [license key](/using-unleash/deploy/license-keys) before upgrading and ensure the license key is configured correctly.

### Passport libraries removed from Open Source Docker distribution

The official `unleashorg/unleash-server` Docker image for Unleash Open Source no longer includes libraries previously used for certain custom authentication methods.

If you were relying on these libraries via a custom authentication hook built into a custom image based on the official one, your authentication will break.

Consider migrating to [Unleash Enterprise](https://www.getunleash.io/pricing) to use [single sign-on](/reference/sso), use password-based authentication, or explore [community-maintained images](https://github.com/Unleash/unleash-docker-community) that may still include these dependencies if absolutely necessary.

### API changes

- The Unleash Edge metrics endpoint `/edge/metrics` has been removed. If you use Unleash Edge, ensure your Edge instances are upgraded to **version 19.1.3 or later** before upgrading the Unleash server to v6 to maintain metrics collection. Core flag evaluation will still work with older Edge versions.
- The legacy feature endpoint `/api/feature`, [deprecated in v4](#legacy-v2-routes-removed), has been removed. Update any integrations still using this endpoint.
- Deprecated import service: The older file-based import functionality at startup has been removed. Use the current [environment import/export features](/how-to/how-to-environment-import-export) or associated APIs.

### Dropped Internet Explorer support

Support for Internet Explorer has been removed, aligning with upstream dependencies (React v18) and Microsoft's end-of-support for the browser.

### Deprecated custom strategies

While still functional in v6, custom strategies are deprecated in favor of using standard strategies combined with [strategy constraints](/reference/activation-strategies#constraints).
Consider migrating if possible, as constraints offer similar flexibility without requiring custom code distribution with SDKs.

### High availability upgrade considerations

If you run multiple Unleash instances in a high-availability setup and are upgrading from a version **below 5.6.11** directly to **version 5.7 or higher**, you might experience temporary UI unavailability during a rolling upgrade while instances with different versions (`<5.7` and `>=5.7`) are running simultaneously.
SDKs are not affected.

To avoid UI downtime, perform a two-step upgrade: first, upgrade all instances to `v5.6.11`. Once all instances are running `v5.6.11`, proceed with the upgrade to `v5.7` or later.

Downgrading from v5.7+ to versions below v5.7 is not straightforward and requires manual database intervention.

### Requires Node.js version 20+

If you run Unleash from source or using a custom build environment (not the official Docker image), you must ensure your environment uses Node.js version 20 or later. Unleash v6 drops support for Node.js versions below 20, which is the [active LTS at the time of release](https://github.com/nodejs/Release/blob/6209d04302e62156b964a605f619283582334c95/README.md#release-schedule).

## Upgrading from v4 to v5

Unleash v5, released on April 27th, 2023, introduced several key changes. Ensure you address the following before or during your upgrade to v5.

### Requires Node.js version 18+

If you run Unleash from source or using a custom build environment (not the official Docker image), you must ensure your environment uses Node.js version 18 or later.
Unleash v5 drops support for Node.js versions below 18, which was the active LTS at the time of release. Unleash v4 officially supported Node.js v14 and v16, both of which reached end of life in 2023.

### The Google Authenticator provider for SSO removed

The Google Authenticator, deprecated in v4, has now been removed. Migrate to using [OpenID Connect](../../how-to/how-to-add-sso-open-id-connect.md) instead.

If you are running a self-hosted version of Unleash and you need to temporarily re-enable the Google Authenticator SSO, you can do so by setting the `GOOGLE_AUTH_ENABLED` environment variable to `true`. If you're running a hosted version of Unleash, you'll need to contact support to request re-enabling the flag.

### Default database password updated

The Unleash default database password was updated to `password`.

This change should only impact development builds and initial setup. You should never use the default password in production environments.

### The /api/admin/features API removed

Most of the old features API was deprecated in v4.3 and superseded by the project API. In v5, the deprecated parts have been completely removed. The only operations remaining on that API path are those to add or remove a tag from a feature flag.

### Error message structure

Some Unleash API error messages changed their structure in v5, specifically those generated by the OpenAPI validation layer. While the structure changed to provide more human-friendly messages and align with other Unleash errors, the error codes remain the same.


Previously, validation errors looked like this:

``` json
{
  "error": "Request validation failed",
  "validation": [
    {
      "keyword": "type",
      "dataPath": ".body.parameters",
      "schemaPath": "#/components/schemas/addonCreateUpdateSchema/properties/parameters/type",
      "params": {
        "type": "object"
      },
      "message": "should be object"
    }
  ]
}
```

Now they look like this:

```json
{
  "id": "37a1765f-a5a0-4371-8aa2-341f331579f9",
  "name": "ValidationError",
  "message": "Request validation failed: the payload you provided doesn't conform to the schema. Check the `details` property for a list of errors that we found.",
  "details": [
    {
      "description": "The .parameters property should be object. You sent [].",
      "path": "parameters"
    }
  ]
}
```

If your integrations rely on the specific structure of these validation error messages, you might need to update your error handling logic.

## Upgrading from v3 to v5

Follow along with our video demonstration on upgrading from v3 to v5 with no downtime in just a few minutes.

<VideoContent videoUrls={["https://www.youtube.com/embed/qmusq_9mE2E"]}/>

## Upgrading from v3 to v4

### All API calls now require a token

In Unleash Open Source v3, client SDKs did not require an API token to connect to the Unleash server. Starting with v4, API token handling, previously an Enterprise feature, was added to the Open Source version. This means that all client SDKs now need to use a client token to connect to Unleash.

Read more in the [API token documentation](../../how-to/how-to-create-api-tokens).

### Configuring Unleash

The options for configuring Unleash changed significantly in v4. If you are manually configuring Unleash, review the updated [configuring Unleash](/using-unleash/deploy/configuring-unleash) documentation.

### Introduced role-based access control

Unleash v4 introduced role-based access control (RBAC), which significantly changed the permission system.

If you implemented custom authentication for your users, you need to make the following changes to your integration:

- The `extendedPermissions` option has been removed. You can no longer specify custom permissions on a per-user basis. All logged-in users must belong to a root role (Admin, Editor, or Viewer). This is handled when creating users via the `userService`.
- All logged-in users need to be defined in Unleash and have a unique ID. This can be achieved by calling `createUser` on the `userService`.

Code example:

```js
const user = userService.loginUserWithoutPassword(
  'some@getunleash.io',
  false, // autoCreateUser. Set to true if you want to create users on the fly.
);

// The user needs to be set on the current active session
req.session.user = user;
```

[Read more about RBAC in our reference documentation](/reference/rbac).

### Legacy v2 routes removed

This is only relevant if you previously used the `enableLegacyRoutes` option.

In v2 you could query feature flags on `/api/features`. This endpoint was deprecated in v4 and we introduced two different endpoints (`/api/admin/features` and `/api/client/features`) to optimize performance and security.
In v3 you could still enable the legacy routes via the `enableLegacyRoutes` option. This was removed in v4.

### Unleash CLI removed

Unleash no longer ships with a binary that allows you to start Unleash directly from the command line. We recommend that you run Unleash [using Docker](/using-unleash/deploy/getting-started).
