quarkusio/quarkus · error · IllegalArgumentException

Only official eclipse-mosquitto images are supported

Error message

Only official eclipse-mosquitto images are supported

What it means

Dev Services for MQTT starts an eclipse-mosquitto container via Testcontainers. The ConfiguredMqttContainer constructor validates the configured Docker image repository and rejects anything that is not an official eclipse-mosquitto image, because the injected mosquitto.conf and startup logic only work with that image layout.

Source

Thrown at extensions/smallrye-reactive-messaging-mqtt/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/mqtt/deployment/MqttDevServicesProcessor.java:189

        private ConfiguredMqttContainer(
                DockerImageName dockerImageName,
                int fixedExposedPort,
                String serviceName,
                String defaultNetworkId,
                boolean useSharedNetwork) {
            super(dockerImageName);
            this.port = fixedExposedPort;
            this.useSharedNetwork = useSharedNetwork;
            withExposedPorts(MQTT_PORT);
            if (serviceName != null) { // Only adds the label in dev mode.
                withLabel(DEV_SERVICE_LABEL, serviceName);
                withLabel(QUARKUS_DEV_SERVICE, serviceName);
            }
            withClasspathResourceMapping("mosquitto.conf",
                    "/mosquitto/config/mosquitto.conf",
                    BindMode.READ_ONLY);
            if (!dockerImageName.getRepository().endsWith("eclipse-mosquitto")) {
                throw new IllegalArgumentException("Only official eclipse-mosquitto images are supported");
            }
            this.hostName = ConfigureUtil.configureNetwork(this, defaultNetworkId, useSharedNetwork, "mqtt");
        }

        @Override
        protected void configure() {
            super.configure();
            if (port > 0) {
                addFixedExposedPort(port, MQTT_PORT);
            }
        }

        @Override
        public String getConnectionInfo() {
            return DevServicesHostUtil.formatPrefixedAuthority("mqtt", getEffectiveHost(), getPort());
        }

        @Override

View on GitHub (pinned to e1c734241f)

Solutions

1. Use an official eclipse-mosquitto image, e.g. eclipse-mosquitto:2.0
2. If you must use a mirror, ensure the repository still ends with eclipse-mosquitto (e.g. registry/example.com/eclipse-mosquitto:2.0)
3. Disable Dev Services or point quarkus.smallrye-reactive-messaging.mqtt.url to an external broker to skip container startup

Example fix

// before
quarkus.smallrye-reactive-messaging.mqtt.devservices.image-name=mycompany/mqtt-broker:latest
// after
quarkus.smallrye-reactive-messaging.mqtt.devservices.image-name=eclipse-mosquitto:2.0

String image = ConfigProvider.getConfig().getValue("quarkus.smallrye-reactive-messaging.mqtt.devservices.image-name", String.class);
if (image != null && !image.split(":")[0].endsWith("eclipse-mosquitto")) {
    throw new IllegalStateException("Dev Services MQTT requires an official eclipse-mosquitto image, got: " + image);
}

static boolean isOfficialMosquitto(String imageName) {
    if (imageName == null) return true;
    String repo = imageName.split(":")[0];
    return repo.endsWith("eclipse-mosquitto");
}

try {
    startDevService();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("eclipse-mosquitto")) {
        log.error("Unsupported MQTT dev-service image; use an official eclipse-mosquitto image");
    }
    throw e;
}

When it happens

Trigger: Setting quarkus.rabbitmq / mqtt dev service image (quarkus.smallrye-reactive-messaging.mqtt.devservices.image-name) to a non-official image whose repository does not end with 'eclipse-mosquitto', e.g. a private registry image or a forked/rebuilt image, while Dev Services is active (dev mode or tests with no broker URL configured).

Common situations: Pointing image-name at a corporate registry mirror (mycompany.com/mqtt), using a custom mosquitto fork, or typos like 'eclipse/mosquitto'.

Related errors

• The fixed port must be greater than 0
• Only official rabbitmq images are supported
• The container image ${dockerImageName} requires you to accep
• Unable to determine datasource URL
• The fixed Kafka port must be greater than 0

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/d37219587faca26d. Report an issue: GitHub.