testcontainers/testcontainers-java · error · java.lang.IllegalStateException

The image requires an Azurite container. Please provide one…

Error message

The image %s requires an Azurite container. Please provide one with the withAzuriteContainer method!

What it means

The Azure Event Hubs emulator image depends on a companion Azurite storage container (for blob checkpoints). EventHubsEmulatorContainer.configure() validates this at container startup and throws IllegalStateException if withAzuriteContainer was never called, because the emulator cannot boot without it.

Solutions

Create an AzuriteContainer, put both containers on the same Network, and call withAzuriteContainer(azurite) before start()
Start the Azurite container (or include it in the same @Testcontainers lifecycle) before the Event Hubs emulator starts
Confirm you use matching versions of AzuriteContainer and the emulator image as per the module docs

Example fix

// before
EventHubsEmulatorContainer eventHubs = new EventHubsEmulatorContainer(DockerImageName.parse("mcr.microsoft.com/azure-messaging/eventhubs-emulator"));
// after
Network network = Network.newNetwork();
AzuriteContainer azurite = new AzuriteContainer(DockerImageName.parse("mcr.microsoft.com/azure-storage/azurite")).withNetwork(network);
EventHubsEmulatorContainer eventHubs = new EventHubsEmulatorContainer(dockerImageName)
    .withNetwork(network)
    .withAzuriteContainer(azurite);

Defensive patterns

Strategy: validation

Validate before calling

EventHubsEmulatorContainer eh = new EventHubsEmulatorContainer(image);
if (eh.getNetworkAliases().isEmpty() || !wiredWithAzurite) // check config before start
    throw new IllegalStateException("Call withAzuriteContainer() with a same-network AzuriteContainer before start()");

Try / catch

try {
    eventHubs.start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("withAzuriteContainer")) {
        throw new IllegalStateException("Test setup bug: Event Hubs emulator needs Azurite", e);
    }
    throw e;
}

Prevention

Encapsulate emulator+Azurite wiring in a shared test fixture/base class
Put both containers on the same Network and start Azurite first
Follow the current testcontainers-azure docs; older examples may omit Azurite

When it happens

Trigger: Creating a new EventHubsEmulatorContainer(dockerImageName) and calling start() (directly or via @Container) without first invoking withAzuriteContainer(azuriteContainer) with an AzuriteContainer on the same network.

Common situations: Upgrading testcontainers-azure from versions before the Azurite requirement was enforced; copying example code that only started the Event Hubs container; forgetting the shared Network between Event Hubs emulator and Azurite.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/b3d114dfcb263a5f. Report an issue: GitHub.

Appendix: source

Thrown at modules/azure/src/main/java/org/testcontainers/azure/EventHubsEmulatorContainer.java:85

    public EventHubsEmulatorContainer withConfig(final Transferable config) {
        withCopyToContainer(config, "/Eventhubs_Emulator/ConfigFiles/Config.json");
        return this;
    }

    /**
     * Accepts the EULA of the container.
     *
     * @return this
     */
    public EventHubsEmulatorContainer acceptLicense() {
        withEnv("ACCEPT_EULA", "Y");
        return this;
    }

    @Override
    protected void configure() {
        if (azuriteContainer == null) {
            throw new IllegalStateException(
                "The image " +
                getDockerImageName() +
                " requires an Azurite container. Please provide one with the withAzuriteContainer method!"
            );
        }
        final String azuriteHost = azuriteContainer.getNetworkAliases().get(0);
        withEnv("BLOB_SERVER", azuriteHost);
        withEnv("METADATA_SERVER", azuriteHost);
        // If license was not accepted programmatically, check if it was accepted via resource file
        if (!getEnvMap().containsKey("ACCEPT_EULA")) {
            LicenseAcceptance.assertLicenseAccepted(this.getDockerImageName());
            acceptLicense();
        }
    }

    /**
     * Returns the connection string.
     *

View on GitHub (pinned to 8e549514e3)