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

The image requires a Microsoft SQL Server container. Please…

Error message

The image %s requires a Microsoft SQL Server container. Please provide one with the withMsSqlServerContainer method!

What it means

The Azure Service Bus emulator image requires a Microsoft SQL Server container as its backing store. ServiceBusEmulatorContainer.configure() checks for it before startup and throws IllegalStateException if withMsSqlServerContainer was never called.

Solutions

Instantiate an MSSQLServerContainer, attach both containers to the same Network, and call withMsSqlServerContainer(mssql) before start()
Ensure the SQL Server container is started (e.g. @Container/@BeforeEach ordering) before the Service Bus emulator
Use an SQL Server image version compatible with the emulator (per module documentation)

Example fix

// before
ServiceBusEmulatorContainer sb = new ServiceBusEmulatorContainer(dockerImageName);
// after
Network network = Network.newNetwork();
MSSQLServerContainer<?> mssql = new MSSQLServerContainer<>(DockerImageName.parse("mcr.microsoft.com/mssql/server:2022-latest")).acceptLicense().withNetwork(network);
ServiceBusEmulatorContainer sb = new ServiceBusEmulatorContainer(dockerImageName)
    .withNetwork(network)
    .withMsSqlServerContainer(mssql);

Defensive patterns

Strategy: validation

Validate before calling

if (serviceBus == null || mssql == null || network == null)
    throw new IllegalStateException("Wire ServiceBusEmulatorContainer with withMsSqlServerContainer() and a shared Network before start()");

Try / catch

try {
    serviceBus.start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("withMsSqlServerContainer")) {
        throw new IllegalStateException("Test setup bug: Service Bus emulator needs SQL Server container", e);
    }
    throw e;
}

Prevention

Create a reusable @Container fixture wiring MSSQL + Service Bus emulator on one network
Remember .acceptLicense() on the MSSQL container
Start dependencies in dependency order (MSSQL before Service Bus emulator)

When it happens

Trigger: Creating a ServiceBusEmulatorContainer(dockerImageName) and calling start() without first invoking withMsSqlServerContainer(msSqlContainer), or without both containers sharing a Network.

Common situations: Following older examples predating the SQL Server prerequisite; defining the MSSQL container in the test class but forgetting to wire it via withMsSqlServerContainer; missing the shared network so the emulator also fails to reach SQL even when configured.

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/9c612c1139b8be7a. Report an issue: GitHub.

Appendix: source

Thrown at modules/azure/src/main/java/org/testcontainers/azure/ServiceBusEmulatorContainer.java:84

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

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

    @Override
    protected void configure() {
        if (msSqlServerContainer == null) {
            throw new IllegalStateException(
                "The image " +
                getDockerImageName() +
                " requires a Microsoft SQL Server container. Please provide one with the withMsSqlServerContainer method!"
            );
        }
        withEnv("SQL_SERVER", msSqlServerContainer.getNetworkAliases().get(0));
        withEnv("MSSQL_SA_PASSWORD", msSqlServerContainer.getPassword());
        // 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.
     *
     * @return connection string

View on GitHub (pinned to 8e549514e3)