What causes "The fixed Kafka port must be greater than 0" in quarkusio/quarkus?

Pass a positive port number (1-65535) to withPort, or don't call it at all to use a dynamically allocated port

quarkusio/quarkus · error · IllegalArgumentException

The fixed Kafka port must be greater than 0

Error message

The fixed Kafka port must be greater than 0

What it means

KafkaContainer.withPort(int) lets you pin the container's exposed Kafka listener to a fixed host port. It validates the argument and throws IllegalArgumentException when the port is negative. The message says 'greater than 0' but the check is fixedPort < 0, so 0 is accepted and means 'no fixed port'. Only negative values actually throw.

Source

Thrown at extensions/kafka-client/deployment/src/main/java/io/quarkus/kafka/client/deployment/KafkaContainer.java:158

                // setup
                "  /opt/kafka/kafka.Kafka " + userOpts + " setup" +
                " --default-configs-dir /etc/kafka/docker" +
                " --mounted-configs-dir /mnt/shared/config" +
                " --final-configs-dir /opt/kafka/config 2>&1 || true\n" +
                // start
                "  KAFKA_LOG4J_CMD_OPTS=\"-Dkafka.logs.dir=/opt/kafka/logs/" +
                " -Dlog4j2.configurationFile=file:/opt/kafka/config/log4j2.yaml\"\n" +
                "  exec /opt/kafka/kafka.Kafka " + userOpts + " start" +
                " --config /opt/kafka/config/server.properties" +
                " $KAFKA_LOG4J_CMD_OPTS $KAFKA_JMX_OPTS ${KAFKA_OPTS-}\n" +
                "else\n" +
                "  exec /etc/kafka/docker/run\n" +
                "fi\n";
    }

    public KafkaContainer withPort(int fixedPort) {
        if (fixedPort < 0) {
            throw new IllegalArgumentException("The fixed Kafka port must be greater than 0");
        } else if (fixedPort > 0) {
            addFixedExposedPort(fixedPort, 9092);
        }
        return this;
    }

    public KafkaContainer withEnv(Map<String, String> envVars) {
        super.withEnv(envVars);
        return this;
    }

    public String getEffectiveHostName() {
        return DevServicesHostUtil.publishedPortHost(getContainerId(), useSharedNetwork, hostName, getHost());
    }

    public int getEffectivePort() {
        return useSharedNetwork ? 9092 : getMappedPort(KAFKA_PORT);
    }

View on GitHub (pinned to e1c734241f)

Solutions

Pass a positive port number (1-65535) to withPort, or don't call it at all to use a dynamically allocated port
Fix the config source so the 'unset' sentinel isn't forwarded (skip withPort when port <= 0)
Validate/normalize the port value before calling withPort

Example fix

// before
container.withPort(Integer.parseInt(System.getProperty("kafka.port", "-1")));
// after
int p = Integer.getInteger("kafka.port", 0);
if (p > 0) container.withPort(p);

Defensive patterns

Strategy: validation

Validate before calling

void safeWithPort(KafkaContainer c, int port) {
    if (port > 0) c.withPort(port); // 0 or negative: use dynamic port instead
}

Type guard

static boolean isFixedPort(int port) { return port > 0 && port <= 65535; }

Try / catch

try {
    container.withPort(port);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("fixed Kafka port")) {
        container = new KafkaContainer(); // dynamic port fallback
    } else throw e;
}

Prevention

Never forward a -1 'unset' sentinel directly to withPort
Validate port ranges (1-65535) when loading from configuration
Omit withPort entirely when a dynamic port is acceptable
Prefer container.getMappedPort(9092) at runtime instead of fixed ports in shared CI environments

When it happens

Trigger: Calling new KafkaContainer(...).withPort(-1) or passing an uninitialized/negative port variable (e.g. from a misconfigured property or a -1 'unset' sentinel) to withPort.

Common situations: Reading a port from config that defaults to -1 for 'dynamic port' and forwarding it directly to withPort; typos in test properties; computing the port via arithmetic that underflows to negative.

Related errors

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