zhisheng17/flink-learning · error · FlinkRuntimeException

{} should be specified to a fixed port. Do not support a ran

Error message

{} should be specified to a fixed port. Do not support a range of ports.

What it means

KubernetesUtils.parsePort reads a string-valued port ConfigOption from the Flink configuration and parses it with Integer.parseInt. Because the option is a String, users can supply a port range like "8081-8090"; that fails parsing and is rethrown as this FlinkRuntimeException. Only a single fixed integer port is acceptable.

Source

Thrown at flink-learning-k8s/flink-k8s/src/main/java/org/apache/flink/kubernetes/utils/KubernetesUtils.java:105

				port.key(),
				fallbackPort);
		}
	}

	/**
	 * Parse a valid port for the config option. A fixed port is expected, and do not support a range of ports.
	 *
	 * @param flinkConfig flink config
	 * @param port port config option
	 * @return valid port
	 */
	public static Integer parsePort(Configuration flinkConfig, ConfigOption<String> port) {
		checkNotNull(flinkConfig.get(port), port.key() + " should not be null.");

		try {
			return Integer.parseInt(flinkConfig.get(port));
		} catch (NumberFormatException ex) {
			throw new FlinkRuntimeException(
				port.key() + " should be specified to a fixed port. Do not support a range of ports.",
				ex);
		}
	}

	/**
	 * Generate name of the Deployment.
	 */
	public static String getDeploymentName(String clusterId) {
		return clusterId;
	}

	/**
	 * Get task manager labels for the current Flink cluster. They could be used to watch the pods status.
	 *
	 * @return Task manager labels.
	 */
	public static Map<String, String> getTaskManagerLabels(String clusterId) {

View on GitHub (pinned to d731cee761)

Solutions

1. Set the port option to a single fixed integer, e.g. rest.port: 8081.
2. Let Flink pick a free port by removing the option instead of specifying a range.
3. Strip whitespace/units from the value; ensure only digits are present.

Example fix

// before
kubernetes.rest-service.exposed.port: 8081-8090
// after
kubernetes.rest-service.exposed.port: 8081

String portStr = flinkConfig.get(portOption);
if (portStr != null && !portStr.trim().matches("\\d+")) {
    throw new IllegalArgumentException(portOption.key() + " must be a single fixed integer port, got: " + portStr);
}

try {
    int port = KubernetesUtils.parsePort(flinkConfig, KubernetesConfigOptions.REST_SERVICE_EXPOSED_PORT);
} catch (FlinkRuntimeException e) {
    LOG.error("Port must be fixed, not a range: {}", e.getMessage());
}

When it happens

Trigger: Setting an exposed/REST/UI/JobManager-RPC port option (e.g. kubernetes.rest-service.exposed.port, rest.port as string) to a range "8081-8091", a comma list, or any non-integer text.

Common situations: Copying Docker-style -p 8081-8090:8081-8090 range syntax into flink-conf.yaml, or leaving template placeholders that don't parse as integers.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Failed to find port "{}" in Service "{}"
• kubernetes.cluster-id must not be blank.
• kubernetes.cluster-id must be no more than {} characters.
• 'kubernetes.jobmanager.replicas' should not be configured le
• Could not get the rest endpoint of ${clusterId}

AI-assisted analysis of zhisheng17/flink-learning@d731cee761 (2026-09-06). Data as JSON: /api/errors/2ceded2aa92ebd50. Report an issue: GitHub.