{"record":{"id":"626fd56a3fd973fa","repo":"quarkusio/quarkus","slug":"the-fixed-kafka-port-must-be-greater-than-0","errorCode":null,"errorMessage":"The fixed Kafka port must be greater than 0","messagePattern":"The fixed Kafka port must be greater than 0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/kafka-client/deployment/src/main/java/io/quarkus/kafka/client/deployment/KafkaContainer.java","lineNumber":158,"sourceCode":"                // setup\n                \"  /opt/kafka/kafka.Kafka \" + userOpts + \" setup\" +\n                \" --default-configs-dir /etc/kafka/docker\" +\n                \" --mounted-configs-dir /mnt/shared/config\" +\n                \" --final-configs-dir /opt/kafka/config 2>&1 || true\\n\" +\n                // start\n                \"  KAFKA_LOG4J_CMD_OPTS=\\\"-Dkafka.logs.dir=/opt/kafka/logs/\" +\n                \" -Dlog4j2.configurationFile=file:/opt/kafka/config/log4j2.yaml\\\"\\n\" +\n                \"  exec /opt/kafka/kafka.Kafka \" + userOpts + \" start\" +\n                \" --config /opt/kafka/config/server.properties\" +\n                \" $KAFKA_LOG4J_CMD_OPTS $KAFKA_JMX_OPTS ${KAFKA_OPTS-}\\n\" +\n                \"else\\n\" +\n                \"  exec /etc/kafka/docker/run\\n\" +\n                \"fi\\n\";\n    }\n\n    public KafkaContainer withPort(int fixedPort) {\n        if (fixedPort < 0) {\n            throw new IllegalArgumentException(\"The fixed Kafka port must be greater than 0\");\n        } else if (fixedPort > 0) {\n            addFixedExposedPort(fixedPort, 9092);\n        }\n        return this;\n    }\n\n    public KafkaContainer withEnv(Map<String, String> envVars) {\n        super.withEnv(envVars);\n        return this;\n    }\n\n    public String getEffectiveHostName() {\n        return DevServicesHostUtil.publishedPortHost(getContainerId(), useSharedNetwork, hostName, getHost());\n    }\n\n    public int getEffectivePort() {\n        return useSharedNetwork ? 9092 : getMappedPort(KAFKA_PORT);\n    }","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/kafka-client/deployment/src/main/java/io/quarkus/kafka/client/deployment/KafkaContainer.java#L140-L176","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\ncontainer.withPort(Integer.parseInt(System.getProperty(\"kafka.port\", \"-1\")));\n// after\nint p = Integer.getInteger(\"kafka.port\", 0);\nif (p > 0) container.withPort(p);","handlingStrategy":"validation","validationCode":"void safeWithPort(KafkaContainer c, int port) {\n    if (port > 0) c.withPort(port); // 0 or negative: use dynamic port instead\n}","typeGuard":"static boolean isFixedPort(int port) { return port > 0 && port <= 65535; }","tryCatchPattern":"try {\n    container.withPort(port);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"fixed Kafka port\")) {\n        container = new KafkaContainer(); // dynamic port fallback\n    } else throw e;\n}","preventionTips":["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"],"tags":["kafka","devservices","testcontainers","validation"],"backgroundTag":"invalid-port-number","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}