For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
13.5kProductPricingSign inStart free trialBook a demo
DocsAPIsSDKsEnterprise EdgeGuidesAcademyRelease notes
DocsAPIsSDKsEnterprise EdgeGuidesAcademyRelease notes
    • Enterprise Edge overview
  • Self-hosted Enterprise Edge
    • Deploy Enterprise Edge
    • Configure Enterprise Edge
    • Configure streaming
    • Migrate from Unleash Proxy
    • Upgrade Enterprise Edge versions

Unleash reduces the risk of releasing new features, drives innovation by streamlining the software release process, and increases revenue by optimizing end-user experience. While we serve the needs of the world's largest, most security-conscious organizations, we are also rated the “Easiest Feature Management system to use” by G2.

GitHubGitHubLinkedInLinkedInX (Twitter)X (Twitter)SlackSlackStack OverflowStack OverflowYouTubeYouTube

Server SDKs

  • Node.js
  • Java
  • Go
  • Rust
  • Ruby
  • Python
  • .NET
  • PHP
  • All SDKs

Frontend SDKs

  • JavaScript
  • React
  • Next.js
  • Vue
  • iOS
  • Android
  • Flutter

Feature Flag use cases

  • Secure, scalable feature flags
  • Rollbacks
  • FedRAMP, SOC2, ISO2700 compliance
  • Progressive or gradual rollouts
  • Trunk-based development
  • Software kill switches
  • A/B testing
  • Feature management
  • Canary releases

Product

  • Quickstart
  • Unleash architecture
  • Pricing
  • Product vision
  • Open live demo
  • Open source
  • Enterprise feature management platform
  • Unleash vs LaunchDarkly

Support

  • Help center
  • Status
  • Changelog
Made in a cosy atmosphere in the Nordic countries.Copyright © 2026 Unleash
LogoLogo
13.5kProductPricingSign inStart free trialBook a demo
On this page
  • Before you upgrade
  • Migrate from v17 to v18
  • What changed
  • Required actions
  • Validate the upgrade
  • Migrate from v18 to v19
  • What changed
  • Required actions
  • Validate the upgrade
  • Migrate from v19 to v20
  • What changed
  • Required actions
  • Validate the upgrade
  • Rollout runbook
  • Rollback criteria
  • Troubleshooting
Self-hosted Enterprise Edge

Upgrade Enterprise Edge versions

||View as Markdown|
Was this page helpful?
Previous
Built with
Edge v17+ Enterprise

This guide walks you through upgrading Enterprise Edge self-hosted from version 17 onward.

Follow each major version upgrade in order: v17 to v18 v18 to v19 v19 to v20

Go to the section that matches your current version to get started.

Migrate from v17 to v18

Service account token creation removed. Start Edge with explicit backend tokens.

Migrate from v18 to v19

Strict and dynamic token-validation modes introduced. Strict mode becomes the default.

Migrate from v19 to v20

Dynamic mode removed. Service account and personal access tokens no longer accepted.

Before you upgrade

Complete this checklist before you upgrade your version:

1

Record your current runtime details

Document the following for your current deployment:

  • Edge image tag and chart version.
  • Environment variables and startup arguments.
  • Persistence configuration (REDIS_URL, S3_BUCKET_NAME, BACKUP_FOLDER), if any.
2

Inventory your tokens

For each token, record the following:

  • Startup tokens configured in TOKENS.
  • The environments and projects each token covers.
  • The SDKs and client applications that depend on each token.
3

Review the release notes

Review the release notes for your target version.

4

Confirm rollback readiness

Verify that you have the following in place:

  • Previous image or chart version is available.
  • Persistence snapshot or backup exists.
  • You have a clear owner and maintenance window for rollback if validation fails.

Migrate from v17 to v18

What changed

v18 removed service-account-driven token creation. Edge no longer creates missing frontend tokens at runtime.

Required actions

Complete the following steps before you upgrade:

1

Start Edge with explicit, valid backend tokens in TOKENS.

2

Verify that your startup tokens cover the environments and projects your frontend SDKs require.

Validate the upgrade

After you upgrade, verify that:

  • Edge starts and reaches READY.
  • Frontend API calls succeed for all expected tokens.
  • No unexpected 401 or 403 errors after cutover.

Migrate from v18 to v19

What changed

v19 introduced two edge mode token-validation behaviors:

  • Strict mode validates incoming tokens against Unleash and only accepts tokens whose project and environment scope matches, or is a subset of, the startup tokens in TOKENS. Strict mode became the default in later v19 builds.
  • Dynamic mode (legacy) allowed Edge to accept previously unseen tokens, validate them upstream, and expand its token coverage at runtime. Dynamic mode is deprecated in v20.

v19.10.0 also added pretrusted token support for teams migrating from the Unleash Proxy.

Required actions

Complete the following steps before you upgrade:

1

Keep TOKENS aligned to your actual usage scope.

2

If you still use dynamic mode, migrate to strict mode before you upgrade to v20. To determine your full token scope:

  • If you use a persistent backup (Redis, S3, or local file), check it to see which tokens Edge previously accepted. This gives a definitive view of the scope dynamic mode was allowing.
  • Monitor your frontend and backend SDK requests along with Edge logs to confirm no expected requests are being rejected.
3

Use PRETRUSTED_TOKENS only when you need temporary compatibility with legacy frontend token secrets during a Proxy migration.

4

Verify that all SDK requests are covered by the startup token scope.

Validate the upgrade

After you upgrade, verify that:

  • Requests across all required environments and projects return correct responses.
  • Token coverage is complete for all known clients.
  • Internal state endpoints (/internal-backstage/tokens, /internal-backstage/features) show expected data.

Migrate from v19 to v20

What changed

v20 enforces the deprecations introduced in v19. Run a full end-to-end validation, not just the items listed below.

  • Dynamic mode was removed. Token validation is strict mode only.
  • Edge no longer accepts service account tokens or personal access tokens as startup tokens in TOKENS.

Required actions

Complete the following steps before you upgrade:

1

Replace any service account or personal access tokens in TOKENS with a backend token that covers the required projects and environments.

2

Remove any DYNAMIC or STRICT behavior toggles from your runtime configuration.

3

Verify that your explicit TOKENS configuration covers all required projects and environments.

4

Validate readiness and feature responses in a staging or UAT environment before you roll out to production.

Validate the upgrade

After you upgrade, verify that:

  • GET /internal-backstage/health returns 200.
  • GET /internal-backstage/ready returns 200.
  • Frontend and backend API responses match expected flag behavior.

Rollout runbook

Follow these steps for each environment, starting with UAT or staging:

1

Deploy the Edge target version with your intended production configuration.

2

Validate health, readiness, and token coverage.

3

Test business-critical application flows.

4

Roll out gradually in production (canary or phased).

5

Re-run validation checks in production.

Rollback criteria

Roll back to the previous version if any of these remain unresolved after remediation:

  • Edge does not consistently reach READY.
  • Critical SDK paths return 401 or 403 unexpectedly.
  • Feature evaluation results are inconsistent for the same token and context.

After rollback, complete a token-scope and persistence analysis before you retry the upgrade.

Troubleshooting

Most upgrade issues stem from removed features that previously masked token-configuration gaps. The following covers the most common failures and how to resolve them.

Frontend SDKs return unauthorized responses

Frontend SDKs start returning unauthorized responses that previously succeeded.

This happens when Edge was relying on a service account token to create frontend tokens at runtime. After the upgrade, Edge no longer does this.

Fix: Verify that the backend tokens in TOKENS cover all environments and projects that your frontend SDKs require.

Intermittent unauthorized responses on both frontend and backend SDKs

After upgrading, some requests succeed while others fail unpredictably across both frontend and backend SDKs.

This typically occurs when Edge runs behind a load balancer with a persistence backup configured. In dynamic mode, Edge accepted previously unseen tokens and expanded its scope at runtime. In strict mode, each Edge instance only serves tokens that fall within the startup token scope. If your backup contains stale state from dynamic mode, different instances behind a load balancer can have different views of which tokens are valid, causing intermittent failures depending on which instance handles the request.

Fix: Verify that the backend tokens in TOKENS cover all environments and projects that your backend SDKs require. If you want to preserve your backup cache, start a single Edge node first with a correct token set and run it for 5 minutes. This forces the backup to a known good state before you scale back up.

Edge fails to start with an invalid token error

Edge does not start and reports that the provided token is not valid.

This happens when TOKENS contains a personal access token or service account token instead of a backend token. v20 rejects these token types at startup.

Fix: Replace the personal access token or service account token with a backend token scoped to the projects and environments your SDKs require.

SDKs receive unauthorized errors despite Edge starting successfully

Edge starts successfully, but downstream SDKs receive unauthorized errors when accessing specific environments.

This is the same root cause as above: TOKENS contains a personal access token or service account token. In some cases Edge starts but the token does not have the correct scope to serve data for the requested environment.

Fix: Replace the personal access token or service account token with a backend token scoped to the projects and environments your SDKs require.