quarkusio/quarkus · error · IllegalArgumentException

The fixed port must be greater than 0

Error message

The fixed port must be greater than 0

What it means

PulsarDevServices' PulsarContainer.withPort(int) exposes a fixed host port mapped to the broker port. It validates the requested port and throws IllegalArgumentException if it is not positive, since Testcontainers cannot bind a non-positive port.

Source

Thrown at extensions/smallrye-reactive-messaging-pulsar/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/pulsar/deployment/PulsarContainer.java:70

    @Override
    protected void containerIsStarting(InspectContainerResponse containerInfo, boolean reused) {
        super.containerIsStarting(containerInfo, reused);
        String host = DevServicesHostUtil.publishedPortHost(containerInfo.getId(), useSharedNetwork, hostName,
                this.getHost());
        String advertisedListeners = "internal:pulsar://localhost:" + BROKER_PORT + ",external:"
                + DevServicesHostUtil.formatPrefixedAuthority("pulsar", host, this.getMappedPort(BROKER_PORT));

        String command = "#!/bin/bash \n";
        command += "export PULSAR_PREFIX_advertisedListeners=" + advertisedListeners + " \n";
        command += "bin/apply-config-from-env.py conf/standalone.conf && bin/pulsar standalone -nfw -nss";
        copyFileToContainer(
                Transferable.of(command.getBytes(StandardCharsets.UTF_8), 700),
                STARTER_SCRIPT);
    }

    public PulsarContainer withPort(final int fixedPort) {
        if (fixedPort <= 0) {
            throw new IllegalArgumentException("The fixed port must be greater than 0");
        }
        addFixedExposedPort(fixedPort, BROKER_PORT);
        return self();
    }

    public String getPulsarBrokerUrl() {
        if (useSharedNetwork) {
            return getServiceUrl(this.hostName, PulsarContainer.BROKER_PORT);
        }
        return getServiceUrl(
                DevServicesHostUtil.publishedPortHost(getContainerId(), this.getHost()),
                this.getMappedPort(BROKER_PORT));
    }

    private String getServiceUrl(String host, int port) {
        return DevServicesHostUtil.formatPrefixedAuthority("pulsar", host, port);
    }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Set the fixed port to a positive value (e.g. quarkus.smallrye-reactive-messaging.pulsar.devservices.fixed-port=8123)
  2. Remove the fixed-port property entirely to let Testcontainers pick a random free port
  3. Check for property override files/env vars that set the port to 0 or a negative number

Example fix

// before
quarkus.smallrye-reactive-messaging.pulsar.devservices.fixed-port=0
// after
quarkus.smallrye-reactive-messaging.pulsar.devservices.fixed-port=8123
Defensive patterns

Strategy: validation

Validate before calling

int fixedPort = ConfigProvider.getConfig().getOptionalValue("quarkus.smallrye-reactive-messaging.pulsar.devservices.fixed-port", Integer.class).orElse(0);
if (fixedPort < 0) {
    throw new IllegalStateException("pulsar devservices fixed-port must be positive or unset, got: " + fixedPort);
}

Type guard

static boolean isValidFixedPort(Integer port) {
    return port == null || port > 0;
}

Try / catch

try {
    container.withPort(fixedPort);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("fixed port")) {
        log.warn("Ignoring invalid fixed port " + fixedPort + ", falling back to random port");
        container.start();
        return;
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling withPort with 0 or a negative int — typically from startPulsarDevService when quarkus.smallrye-reactive-messaging.pulsar.devservices.fixed-port resolves to a value <= 0 (unset default mishandled or a zero/negative value configured).

Common situations: Setting quarkus.smallrye-reactive-messaging.pulsar.devservices.fixed-port=0 expecting a random port; configuration binding failures yielding 0.

Related errors

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