zhisheng17/flink-learning · error · IllegalConfigurationException

High availability should be enabled when starting standby…

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.

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').

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• already exists in ConfigMap
• ConfigMap does not exists. It may be deleted externally.
• Could not find in ConfigMap
• Could not find in ConfigMap
• Could not properly remove all state handles.

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

Appendix: 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)