{"record":{"id":"5086f43b481ecc27","repo":"apache/pulsar","slug":"metrics-port-need-to-be-within-the-range-of-0-and","errorCode":null,"errorMessage":"Metrics port need to be within the range of 0 and 65535","messagePattern":"Metrics port need to be within the range of 0 and 65535","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/localrun/src/main/java/org/apache/pulsar/functions/LocalRunner.java","lineNumber":572,"sourceCode":"                null, /* extra dependencies dir */\n                narExtractionDirectory, /* nar extraction dir */\n                secretsProviderConfigurator,\n                false, Optional.empty(), Optional.empty());\n\n        for (int i = 0; i < parallelism; ++i) {\n            InstanceConfig instanceConfig = new InstanceConfig();\n            instanceConfig.setFunctionDetails(functionDetails);\n            // TODO: correctly implement function version and id\n            instanceConfig.setFunctionVersion(UUID.randomUUID().toString());\n            instanceConfig.setFunctionId(UUID.randomUUID().toString());\n            instanceConfig.setInstanceId(i + instanceIdOffset);\n            instanceConfig.setMaxBufferedTuples(1024);\n            instanceConfig.setPort(FunctionCommon.findAvailablePort());\n\n            if (metricsPortStart != null) {\n                int metricsPort = metricsPortStart + i;\n                if (metricsPortStart < 0 || metricsPortStart > 65535) {\n                    throw new IllegalArgumentException(\"Metrics port need to be within the range of 0 and 65535\");\n                }\n                instanceConfig.setMetricsPort(metricsPort);\n            } else {\n                instanceConfig.setMetricsPort(FunctionCommon.findAvailablePort());\n            }\n            instanceConfig.setClusterName(\"local\");\n            if (functionConfig != null) {\n                instanceConfig.setMaxPendingAsyncRequests(functionConfig.getMaxPendingAsyncRequests());\n                if (functionConfig.getExposePulsarAdminClientEnabled() != null) {\n                    instanceConfig\n                            .setExposePulsarAdminClientEnabled(functionConfig.getExposePulsarAdminClientEnabled());\n                }\n            }\n\n            RuntimeSpawner runtimeSpawner = new RuntimeSpawner(\n                    instanceConfig,\n                    userCodeFile,\n                    null,","sourceCodeStart":554,"sourceCodeEnd":590,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/localrun/src/main/java/org/apache/pulsar/functions/LocalRunner.java#L554-L590","documentation":"In process mode (startProcessMode), when metricsPortStart is set, each instance i gets metricsPortStart + i. LocalRunner validates metricsPortStart is in [0, 65535] and throws IllegalArgumentException otherwise. Note the check happens after computing the port, and the range check is on the base port, not per-instance, so a high base can still overflow instance ports.","triggerScenarios":"Starting LocalRunner with setMetricsPortStart(-1) or a value > 65535 in process runtime mode.","commonSituations":"Misconfigured port derived from an env variable (empty/-1); copy-paste of an instance index into the base port field; port collisions prompting users to guess large values.","solutions":["Set metricsPortStart to a value between 0 and 65535 (with headroom for parallelism instances)","Leave metricsPortStart null to let the runner pick available ports automatically","Validate the env/property driving this value before setting it"],"exampleFix":"// before\nrunner.setMetricsPortStart(Integer.parseInt(env.get(\"METRICS_PORT\"))); // env missing -> -1?\n// after\nint port = Integer.parseInt(env.getOrDefault(\"METRICS_PORT\", \"0\"));\nif (port < 0 || port > 65535) {\n    throw new IllegalArgumentException(\"METRICS_PORT out of range\");\n}\nrunner.setMetricsPortStart(port);","handlingStrategy":"validation","validationCode":"if (metricsPortStart != null && (metricsPortStart < 0 || metricsPortStart > 65535)) {\n    throw new IllegalArgumentException(\"metricsPortStart must be 0-65535\");\n}\nrunner.setMetricsPortStart(metricsPortStart);","typeGuard":null,"tryCatchPattern":"try {\n    runner.start(true);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Metrics port\")) {\n        // correct metricsPortStart and restart with a new runner\n    }\n}","preventionTips":["Validate env-derived port values before setting","Leave metricsPortStart null for auto port selection","Reserve headroom for parallelism instance ports"],"tags":["configuration","port","validation"],"backgroundTag":"invalid-port-range","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}