zhisheng17/flink-learning · error · IllegalArgumentException

Unknown Kubernetes deployment target "${deploymentTargetStr}

Error message

Unknown Kubernetes deployment target "${deploymentTargetStr}". The available options are: ${options()}

What it means

KubernetesDeploymentTarget.fromConfig validates DeploymentOptions.TARGET against the known Kubernetes targets (kubernetes-session, kubernetes-application, case-insensitive). If the configured value is null or unrecognized, an IllegalArgumentException listing the valid options is thrown.

Source

Thrown at flink-learning-k8s/flink-k8s/src/main/java/org/apache/flink/kubernetes/configuration/KubernetesDeploymentTarget.java:52

public enum KubernetesDeploymentTarget {

	SESSION("kubernetes-session"),
	APPLICATION("kubernetes-application");

	private final String name;

	KubernetesDeploymentTarget(final String name) {
		this.name = checkNotNull(name);
	}

	public static KubernetesDeploymentTarget fromConfig(final Configuration configuration) {
		checkNotNull(configuration);

		final String deploymentTargetStr = configuration.get(DeploymentOptions.TARGET);
		final KubernetesDeploymentTarget deploymentTarget = getFromName(deploymentTargetStr);

		if (deploymentTarget == null) {
			throw new IllegalArgumentException(
					"Unknown Kubernetes deployment target \"" + deploymentTargetStr + "\"." +
							" The available options are: " + options());
		}
		return deploymentTarget;
	}

	public String getName() {
		return name;
	}

	public static boolean isValidKubernetesTarget(final String configValue) {
		return configValue != null &&
				Arrays.stream(KubernetesDeploymentTarget.values())
						.anyMatch(kubernetesDeploymentTarget -> kubernetesDeploymentTarget.name.equalsIgnoreCase(configValue));
	}

	private static KubernetesDeploymentTarget getFromName(final String deploymentTarget) {
		if (deploymentTarget == null) {

View on GitHub (pinned to d731cee761)

Solutions

1. Set target to kubernetes-application: flink run-application -t kubernetes-application ... (or kubernetes-session for session mode).
2. Fix typos in deployment.target in flink-conf.yaml or the command line; only the two listed values are valid.
3. If programmatically building the config, call configuration.set(DeploymentOptions.TARGET, ...) before deployment, or pre-validate with KubernetesDeploymentTarget.isValidKubernetesTarget(value).

Example fix

// before
config.set(DeploymentOptions.TARGET, "kubernetes-app");
// after
config.set(DeploymentOptions.TARGET, "kubernetes-application");

String target = config.get(DeploymentOptions.TARGET);
if (!KubernetesDeploymentTarget.isValidKubernetesTarget(target)) {
    throw new IllegalArgumentException("Invalid deployment.target: " + target + " (use kubernetes-session|kubernetes-application)");
}

try {
    descriptor.deployApplicationCluster(spec, appConfig);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown Kubernetes deployment target")) {
        config.set(DeploymentOptions.TARGET, "kubernetes-application");
    }
}

When it happens

Trigger: Reading deployment.target from the Flink configuration during Kubernetes deployment when it is unset (null) or set to anything other than 'kubernetes-session'/'kubernetes-application'.

Common situations: Typo like 'kubernetes-app' or 'k8s-application'; forgetting -t on the flink command line; leftover target 'local'/'remote'/'yarn' in a config reused for Kubernetes; case-sensitive tooling that lowercased the value differently (matching is case-insensitive, so usually a real misspelling).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Couldn't deploy Kubernetes Application Cluster. Expected dep
• Could not get the rest endpoint of ${clusterId}
• Could not create the RestClusterClient.
• The Flink cluster ${clusterId} already exists.
• 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/d1fe1069fb7920db. Report an issue: GitHub.