zhisheng17/flink-learning · error · IllegalArgumentException

Only "local" is supported as schema for application mode. Th

Error message

Only "local" is supported as schema for application mode. This assumes that the jar is located in the image, not the Flink client. An example of such path is: local:///opt/flink/examples/streaming/WindowJoin.jar

What it means

KubernetesUtils.checkJarFileForApplicationMode validates the user jar URI when running in Kubernetes application mode. Only 'local://' scheme URIs are accepted because the jar must be baked into the container image, not fetched from the client machine; any other scheme throws this IllegalArgumentException.

Source

Thrown at flink-learning-k8s/flink-k8s/src/main/java/org/apache/flink/kubernetes/utils/KubernetesUtils.java:366

		startCommandValues.put("logging",
			getLogging(logDirectory + "/" + fileName, configDirectory, hasLogback, hasLog4j));
		startCommandValues.put("class", mainClass);

		startCommandValues.put("args", mainArgs != null ? mainArgs : "");

		final String commandTemplate = flinkConfig.getString(KubernetesConfigOptions.CONTAINER_START_COMMAND_TEMPLATE);
		return BootstrapTools.getStartCommand(commandTemplate, startCommandValues);
	}

	public static List<File> checkJarFileForApplicationMode(Configuration configuration) {
		return configuration.get(PipelineOptions.JARS).stream().map(
			FunctionUtils.uncheckedFunction(
				uri -> {
					final URI jarURI = PackagedProgramUtils.resolveURI(uri);
					if (jarURI.getScheme().equals("local") && jarURI.isAbsolute()) {
						return new File(jarURI.getPath());
					}
					throw new IllegalArgumentException("Only \"local\" is supported as schema for application mode." +
							" This assumes that the jar is located in the image, not the Flink client." +
							" An example of such path is: local:///opt/flink/examples/streaming/WindowJoin.jar");
				})
		).collect(Collectors.toList());
	}

	private static String getJavaOpts(Configuration flinkConfig, ConfigOption<String> configOption) {
		String baseJavaOpts = flinkConfig.getString(CoreOptions.FLINK_JVM_OPTIONS);

		if (flinkConfig.getString(configOption).length() > 0) {
			return baseJavaOpts + " " + flinkConfig.getString(configOption);
		} else {
			return baseJavaOpts;
		}
	}

	private static String getLogging(String fileName, String confDir, boolean hasLogback, boolean hasLog4j) {
		StringBuilder logging = new StringBuilder();

View on GitHub (pinned to d731cee761)

Solutions

1. Change the jar argument to local:///<path-inside-image>, e.g. local:///opt/flink/usrlib/job.jar.
2. COPY the jar into the image at that path (e.g. under /opt/flink/usrlib/) and rebuild the image.
3. Use session or per-job mode instead if you need to upload a local jar from the client.

Example fix

// before
./bin/flink run -t kubernetes-application -c MainClass /home/me/job.jar
// after (with jar at /opt/flink/usrlib/job.jar in the image)
./bin/flink run -t kubernetes-application -c MainClass local:///opt/flink/usrlib/job.jar

URI uri = PackagedProgramUtils.resolveURI(jarArg);
if (!("local".equals(uri.getScheme()) && uri.isAbsolute())) {
    throw new IllegalArgumentException("Application mode jar must use local:/// scheme: " + jarArg);
}

try {
    KubernetesUtils.checkJarFileForApplicationMode(flinkConfig);
} catch (IllegalArgumentException e) {
    LOG.error("Application mode requires local:/// jar inside the image: {}", e.getMessage());
}

When it happens

Trigger: Submitting with -t kubernetes-application and a jar argument like /path/to/job.jar, file:///path/job.jar, or http://.../job.jar instead of local:///path/in/image/job.jar.

Common situations: Reusing a client-mode submission command unchanged for application mode, or forgetting to COPY the jar into the custom image while pointing at the local filesystem path.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Could not get the rest endpoint of ${clusterId}
• Could not create the RestClusterClient.
• The Flink cluster ${clusterId} already exists.
• 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/44ade6211d17d6fe. Report an issue: GitHub.