zhisheng17/flink-learning · error · IllegalConfigurationException

High availability should be enabled when starting standby Jo

Error message

High availability should be enabled when starting standby JobManagers.

What it means

getReplicas additionally rejects kubernetes.jobmanager.replicas > 1 when high availability is not activated. Multiple JobManager replicas only make sense with HA (leader election via Kubernetes/Kubernetes ConfigMap or ZooKeeper); without it standby JobManagers would be useless or conflicting, so the library refuses to start them.

Source

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

	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. Enable HA: high-availability: org.apache.flink.kubernetes.highavailability.KubernetesHaServicesFactory plus storage path settings (high-availability.storageDir).
2. If you don't want HA, set kubernetes.jobmanager.replicas back to 1.
3. Verify high-availability mode is recognized: check HighAvailabilityMode.isHighAvailabilityModeActivated over your effective config (ZOOKEEPER or FACTORY_CLASS set).

Example fix

// before
kubernetes.jobmanager.replicas: 2
// after
high-availability: org.apache.flink.kubernetes.highavailability.KubernetesHaServicesFactory
high-availability.storageDir: s3://bucket/flink/ha
kubernetes.jobmanager.replicas: 2

int replicas = flinkConfig.get(KubernetesConfigOptions.KUBERNETES_JOBMANAGER_REPLICAS);
boolean ha = HighAvailabilityMode.isHighAvailabilityModeActivated(flinkConfig);
if (replicas > 1 && !ha) {
    throw new IllegalArgumentException("replicas>1 requires high-availability to be enabled");
}

try {
    int replicas = jmParameters.getReplicas();
} catch (IllegalConfigurationException e) {
    LOG.error("Enable HA or reduce replicas: {}", e.getMessage());
}

When it happens

Trigger: Configuring kubernetes.jobmanager.replicas >= 2 without setting high-availability to Kubernetes (or ZooKeeper), e.g. -Dkubernetes.jobmanager.replicas=3 without high-availability: org.apache.flink.kubernetes.highavailability.KubernetesHaServicesFactory.

Common situations: Users enabling replicas for fault tolerance but forgetting HA setup, copying HA cluster configs partially, or enabling HA with the wrong mode value that isHighAvailabilityModeActivated does not recognize (e.g. 'NONE').

Related errors

• Failed to update ConfigMap {} since current KubernetesCheckp
• Failed to clear job state in ConfigMap {} for job {}
• Failed to set {} state in ConfigMap {} for job {}
• {} already exists in ConfigMap {}
• Could not find {} in ConfigMap {}

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