How to build resilience by bootstrapping Unleash’s Java SDK with predefined values [2023]

How resilient is your current feature management system? What happens if failing network requests keep you from reaching your feature management service?

You don’t want a situation where your app is unable to function properly because the feature flag configuration can’t be loaded.

As part of our commitment to resilience and robustness, we introduced additional strategies for bootstrapping predefined values. This is part of your feature flag best practices.

The first SDK to receive this feature was the Java SDK, available as of our 4.2.1 release. Later releases brought predefined values for:

Today we’ll be focusing on Java.

So, what’s a bootstrap?

Bootstrap refers to providing the SDK with predefined values for the feature flag configuration. This will allow Unleash SDK to execute independently of the network connection

This makes sense in situations when the client application network connection towards the Unleash server is not available during boot up.

By preloading values you also can define permanent storage in areas where the SDK does not have access to permanent storage, like in a container.

Before getting started, you should update your Unleash client dependency. At the time of this writing, the latest Java version is 7.1.0.

Load order

The Unleash client SDK already performs regular backups of the latest known state from the API.

On startup, if a backup file is available, it will take priority over the bootstrap provider. It is not currently possible to override this priority. If you’re sure you want to load your bootstrap, delete the backup file. It’s usually found in the /tmp folder.

If there’s no backup file, or the backup file contains no feature flags, the Unleash client SDK will try loading state using the bootstrap handler.

Using a file on disk

By default, the Unleash client SDK configures a ToggleBootstrapFileProvider which loads the file specified by the UNLEASH_BOOTSTRAP_FILE environment variable.

This variable should be set to the location of a downloaded backup of your feature flags.

A minimal Dockerfile to prebake the latest known state from your Unleash instance at build time could look something like this:


Using a file on classpath

The ToggleBootstrapFileProvider also supports loading from the running applications classpath. So if you’re baking your feature flag state into a fatjar, for example, that’s what you should use.

For instance, if you’ve stored your JSON at /toggles/bootstrap.json inside the jar, set UNLEASH_BOOTSTRAP_FILE to classpath:/toggles/bootstrap.json. The SDK will load the packaged json file.

Using S3 to store feature flags​

To avoid bloating the core library with extra dependencies, we’ve only included support for loading feature flags from the disk. However, the ToggleBootstrapProvider interface is public and only has a single method to implement. Adding support for AWS S3 should be pretty easy.

First, you’ll need to add S3 library to your classpath. The Maven coordinates are:

  • GroupId: software.amazon.awssdk
  • artifactId: s3
  • version: 2.16.29 (or newer)

Then use this when configuring Unleash:

Configure S3 in Unleash

This should allow you to have code that syncs state from the Unleash API server to an S3 bucket. Use this to get your Java application to a known toggle state at startup.


All code used in this post is available in the Unleash Java SDK examples repo.

Want to get started using Unleash with Java?


Updated March 2023

Share this article