zhisheng17/flink-learning · error · IllegalArgumentException

kubernetes.cluster-id must not be blank.

Error message

kubernetes.cluster-id must not be blank.

What it means

AbstractKubernetesParameters.getClusterId reads kubernetes.cluster-id from the Flink configuration and throws IllegalArgumentException when it is blank (null, empty, or whitespace). A cluster-id is mandatory for every Kubernetes operation since it names all Kubernetes resources the Flink cluster creates.

Source

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

	public Configuration getFlinkConfiguration() {
		return flinkConfig;
	}

	@Override
	public String getConfigDirectory() {
		final String configDir = flinkConfig.getOptional(DeploymentOptionsInternal.CONF_DIR).orElse(
			flinkConfig.getString(KubernetesConfigOptions.FLINK_CONF_DIR));

		checkNotNull(configDir);
		return configDir;
	}

	@Override
	public String getClusterId() {
		final String clusterId = flinkConfig.getString(KubernetesConfigOptions.CLUSTER_ID);

		if (StringUtils.isBlank(clusterId)) {
			throw new IllegalArgumentException(KubernetesConfigOptions.CLUSTER_ID.key() + " must not be blank.");
		} else if (clusterId.length() > Constants.MAXIMUM_CHARACTERS_OF_CLUSTER_ID) {
			throw new IllegalArgumentException(KubernetesConfigOptions.CLUSTER_ID.key() + " must be no more than " +
				Constants.MAXIMUM_CHARACTERS_OF_CLUSTER_ID + " characters.");
		}

		return clusterId;
	}

	@Override
	public String getNamespace() {
		final String namespace = flinkConfig.getString(KubernetesConfigOptions.NAMESPACE);
		checkArgument(!namespace.trim().isEmpty(), "Invalid " + KubernetesConfigOptions.NAMESPACE + ".");

		return namespace;
	}

	@Override
	public String getImage() {

View on GitHub (pinned to d731cee761)

Solutions

1. Set kubernetes.cluster-id in flink-conf.yaml or pass -Dkubernetes.cluster-id=<name> on the command line.
2. Fix shell quoting/expansion so the variable actually contains a value (e.g. "${CLUSTER_ID:?unset}").
3. Validate the config before submission (KubernetesUtils.checkAndUpdateOrCreateClusterId or your own check).

Example fix

// before
./bin/flink run -t kubernetes-application ...
// after
./bin/flink run -t kubernetes-application -Dkubernetes.cluster-id=my-flink-cluster ...

String clusterId = flinkConfig.get(KubernetesConfigOptions.CLUSTER_ID);
if (clusterId == null || clusterId.trim().isEmpty()) {
    throw new IllegalArgumentException("kubernetes.cluster-id must be set before Kubernetes submission");
}

try {
    String id = parameters.getClusterId();
} catch (IllegalArgumentException e) {
    LOG.error("Missing kubernetes.cluster-id: pass -Dkubernetes.cluster-id=<name>");
    return;
}

When it happens

Trigger: Calling any Kubernetes parameters method (directly or via getCommonLabels) when kubernetes.cluster-id was never set, set to an empty string, or set to whitespace only.

Common situations: Submitting to Kubernetes without -Dkubernetes.cluster-id=..., a script with an unexpanded $CLUSTER_ID variable resolving to empty, or loading a flink-conf.yaml missing the key.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• kubernetes.cluster-id must be no more than {} characters.
• 'kubernetes.jobmanager.replicas' should not be configured le
• {} should be specified to a fixed port. Do not support a ran
• No measurement defined
• The given argument is no array.

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