zhisheng17/flink-learning · error · IllegalArgumentException

kubernetes.cluster-id must be no more than {} characters.

Error message

kubernetes.cluster-id must be no more than {} characters.

What it means

getClusterId also enforces a maximum length: if the kubernetes.cluster-id value is longer than Constants.MAXIMUM_CHARACTERS_OF_CLUSTER_ID (63, the Kubernetes label/DNS-name limit) it throws IllegalArgumentException. Kubernetes object names and label values must be at most 63 characters, so longer ids would produce invalid resources.

Source

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

	}

	@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() {
		final String containerImage = flinkConfig.getString(KubernetesConfigOptions.CONTAINER_IMAGE);
		checkArgument(!containerImage.trim().isEmpty(),

View on GitHub (pinned to d731cee761)

Solutions

1. Shorten kubernetes.cluster-id to 63 characters or fewer.
2. Hash or truncate the long name (e.g. first 40 chars + short hash) when generating it programmatically.
3. Add a pre-submit assertion on the length in your deployment script.

Example fix

// before
clusterId = "team-prod-flink-session-cluster-us-east-1-a-" + longUuid; // > 63 chars
// after
clusterId = ("team-prod-flink-" + Integer.toHexString(longUuid.hashCode())).substring(0, Math.min(63, ...));

String clusterId = flinkConfig.get(KubernetesConfigOptions.CLUSTER_ID);
if (clusterId != null && clusterId.length() > 63) {
    clusterId = clusterId.substring(0, 63);
    flinkConfig.set(KubernetesConfigOptions.CLUSTER_ID, clusterId);
}

try {
    String id = parameters.getClusterId();
} catch (IllegalArgumentException e) {
    LOG.error("cluster-id too long, shorten to <= 63 chars");
}

When it happens

Trigger: Setting kubernetes.cluster-id to a string longer than 63 characters, e.g. auto-generated names concatenating app name, environment, timestamp, or a long UUID.

Common situations: CI pipelines deriving cluster-id from long branch/job names, teams embedding full deployment names into the cluster id, or templated names exceeding the limit.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• kubernetes.cluster-id must not be blank.
• '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/ab70216785089594. Report an issue: GitHub.