zhisheng17/flink-learning · error · IllegalConfigurationException

'kubernetes.jobmanager.replicas' should not be configured le

Error message

'kubernetes.jobmanager.replicas' should not be configured less than one.

What it means

KubernetesJobManagerParameters.getReplicas validates kubernetes.jobmanager.replicas and throws IllegalConfigurationException when the configured value is less than 1. A JobManager deployment needs at least one replica; zero or negative values are meaningless for running a Flink cluster.

Source

Thrown at flink-learning-k8s/flink-k8s/src/main/java/org/apache/flink/kubernetes/kubeclient/parameters/KubernetesJobManagerParameters.java:161

		final String entrypointClass = flinkConfig.getString(KubernetesConfigOptionsInternal.ENTRY_POINT_CLASS);
		checkNotNull(entrypointClass, KubernetesConfigOptionsInternal.ENTRY_POINT_CLASS + " must be specified!");

		return entrypointClass;
	}

	public KubernetesConfigOptions.ServiceExposedType getRestServiceExposedType() {
		return flinkConfig.get(KubernetesConfigOptions.REST_SERVICE_EXPOSED_TYPE);
	}

	public boolean isInternalServiceEnabled() {
		return !HighAvailabilityMode.isHighAvailabilityModeActivated(flinkConfig);
	}

	public int getReplicas() {
		final int replicas =
			flinkConfig.get(KubernetesConfigOptions.KUBERNETES_JOBMANAGER_REPLICAS);
		if (replicas < 1) {
			throw new IllegalConfigurationException(
				String.format(
					"'%s' should not be configured less than one.",
					KubernetesConfigOptions.KUBERNETES_JOBMANAGER_REPLICAS.key()));
		} else if (replicas > 1
			&& !HighAvailabilityMode.isHighAvailabilityModeActivated(flinkConfig)) {
			throw new IllegalConfigurationException(
				"High availability should be enabled when starting standby JobManagers.");
		}
		return replicas;
	}
}

View on GitHub (pinned to d731cee761)

Solutions

1. Set kubernetes.jobmanager.replicas to 1 or higher (default is 1).
2. To scale down to zero, delete the cluster instead of setting replicas to 0.
3. Guard script-generated values: [ "$REPLICAS" -ge 1 ] || REPLICAS=1 before writing the config.

Example fix

// before
kubernetes.jobmanager.replicas: 0
// after
kubernetes.jobmanager.replicas: 1

Integer replicas = flinkConfig.get(KubernetesConfigOptions.KUBERNETES_JOBMANAGER_REPLICAS);
if (replicas != null && replicas < 1) {
    flinkConfig.set(KubernetesConfigOptions.KUBERNETES_JOBMANAGER_REPLICAS, 1);
}

try {
    int replicas = jmParameters.getReplicas();
} catch (IllegalConfigurationException e) {
    LOG.error("Invalid jobmanager.replicas: {}", e.getMessage());
}

When it happens

Trigger: Setting kubernetes.jobmanager.replicas to 0 or a negative number, then calling createJobManagerDeployment (e.g. via the standalone Kubernetes session/application bootstrap).

Common situations: Typo'd config values, scripts computing replicas via arithmetic that underflows, users attempting to "scale to zero" a session cluster by setting replicas to 0.

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

• kubernetes.cluster-id must not be blank.
• kubernetes.cluster-id must be no more than {} characters.
• High availability should be enabled when starting standby Jo
• {} should be specified to a fixed port. Do not support a ran
• Could not get the rest endpoint of ${clusterId}

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