zhisheng17/flink-learning · error · ClusterDeploymentException

The Flink cluster ${clusterId} already exists.

Error message

The Flink cluster ${clusterId} already exists.

What it means

Thrown by deployApplicationCluster when a Kubernetes service for the target clusterId already exists, indicating a Flink cluster with that name is already deployed. It is a guard against deploying duplicate clusters and colliding Kubernetes resources.

Source

Thrown at flink-learning-k8s/flink-k8s/src/main/java/org/apache/flink/kubernetes/KubernetesClusterDescriptor.java:168

			clusterSpecification,
			false);

		try (ClusterClient<String> clusterClient = clusterClientProvider.getClusterClient()) {
			LOG.info(
				"Create flink session cluster {} successfully, JobManager Web Interface: {}",
				clusterId,
				clusterClient.getWebInterfaceURL());
		}
		return clusterClientProvider;
	}

	@Override
	public ClusterClientProvider<String> deployApplicationCluster(
			final ClusterSpecification clusterSpecification,
			final ApplicationConfiguration applicationConfiguration) throws ClusterDeploymentException {
		//todo：k8s application mode
		if (client.getService(KubernetesService.ServiceType.REST_SERVICE, clusterId).isPresent()) {
			throw new ClusterDeploymentException("The Flink cluster " + clusterId + " already exists.");
		}

		checkNotNull(clusterSpecification);
		checkNotNull(applicationConfiguration);

		final KubernetesDeploymentTarget deploymentTarget = KubernetesDeploymentTarget.fromConfig(flinkConfig);
		if (KubernetesDeploymentTarget.APPLICATION != deploymentTarget) {
			throw new ClusterDeploymentException(
				"Couldn't deploy Kubernetes Application Cluster." +
					" Expected deployment.target=" + KubernetesDeploymentTarget.APPLICATION.getName() +
					" but actual one was \"" + deploymentTarget + "\"");
		}

		applicationConfiguration.applyToConfiguration(flinkConfig);

		// No need to do pipelineJars validation if it is a PyFlink job.
		if (!(PackagedProgramUtils.isPython(applicationConfiguration.getApplicationClassName()) ||
			PackagedProgramUtils.isPython(applicationConfiguration.getProgramArguments()))) {

View on GitHub (pinned to d731cee761)

Solutions

1. Pick a unique cluster-id (e.g. append a timestamp/UUID) for the new deployment.
2. Kill the existing cluster first: flink kill / KubernetesClusterDescriptor.killCluster(clusterId), or kubectl delete deployments/svc with the cluster's labels.
3. Check for residual resources with kubectl get svc,deploy | grep <clusterId> and clean them up manually.
4. Ensure only one submission process runs per cluster-id (avoid concurrent submits).

Example fix

// before
String clusterId = "my-flink-cluster";
descriptor.deployApplicationCluster(spec, appConfig);
// after
String clusterId = "my-flink-cluster-" + UUID.randomUUID().toString().substring(0, 8);
descriptor.deployApplicationCluster(spec, appConfig);

boolean exists = kubeClient.getService(KubernetesService.ServiceType.REST_SERVICE, clusterId).isPresent();
if (exists) { /* delete old cluster or pick a new clusterId */ }

try {
    descriptor.deployApplicationCluster(spec, appConfig);
} catch (ClusterDeploymentException e) {
    if (e.getMessage().contains("already exists")) {
        descriptor.killCluster(clusterId); // then redeploy
    }
}

When it happens

Trigger: Calling deployApplicationCluster while a REST service with the same clusterId is present in the namespace (previous deployment not cleaned up, or an intentional name reuse).

Common situations: Re-running a job submission script without killing the old cluster; leftover resources from a crashed deployment; two concurrent submissions using the same cluster-id in one namespace; switching from session to application mode with a reused cluster-id.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• Could not create Kubernetes cluster "${clusterId}".
• Could not get the rest endpoint of ${clusterId}
• Could not create the RestClusterClient.
• Couldn't deploy Kubernetes Application Cluster. Expected dep
• Per-Job Mode not supported by Active Kubernetes deployments.

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