apache/flink · error · CompletionException

Failed to get the FileSystem of artifact {artifactFilePath}.

Error message

Failed to get the FileSystem of artifact {artifactFilePath}.

What it means

Thrown when RestClusterClient.submitJob cannot resolve the FileSystem for a distributed-cache artifact path. Before uploading local artifacts, the client calls artifactFilePath.getFileSystem() to check isDistributedFS(). If the artifact path uses an unrecognized or unsupported scheme (e.g., s3:// without the S3 filesystem plugin loaded), this IOException is caught and wrapped in a FlinkException.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/program/rest/RestClusterClient.java:428

                            for (Map.Entry<String, DistributedCache.DistributedCacheEntry>
                                    artifacts : executionPlan.getUserArtifacts().entrySet()) {
                                final Path artifactFilePath =
                                        new Path(artifacts.getValue().filePath);
                                try {
                                    // Only local artifacts need to be uploaded.
                                    if (!artifactFilePath.getFileSystem().isDistributedFS()) {
                                        artifactFileNames.add(
                                                new JobSubmitRequestBody.DistributedCacheFile(
                                                        artifacts.getKey(),
                                                        artifactFilePath.getName()));
                                        filesToUpload.add(
                                                new FileUpload(
                                                        Paths.get(artifactFilePath.getPath()),
                                                        RestConstants.CONTENT_TYPE_BINARY));
                                    }
                                } catch (IOException e) {
                                    throw new CompletionException(
                                            new FlinkException(
                                                    "Failed to get the FileSystem of artifact "
                                                            + artifactFilePath
                                                            + ".",
                                                    e));
                                }
                            }

                            final JobSubmitRequestBody requestBody =
                                    new JobSubmitRequestBody(
                                            executionPlanFile.getFileName().toString(),
                                            jarFileNames,
                                            artifactFileNames);

                            return Tuple2.of(
                                    requestBody, Collections.unmodifiableCollection(filesToUpload));
                        });

View on GitHub (pinned to 2f3c205e92)

Solutions

1. If the artifact is local, use a local file:// path or a plain filesystem path instead of a distributed FS scheme.
2. Add the missing filesystem plugin JAR (e.g., flink-s3-fs-hadoop or flink-hadoop-fs) to Flink's lib/ directory and the client classpath.
3. Verify the artifact path is well-formed and the scheme is supported by checking FileSystem.get(URI) manually.
4. Ensure all required Hadoop or cloud-storage configuration (core-site.xml, flink-conf.yaml) is on the client.

Example fix

// before — artifact path uses scheme without plugin
env.registerCachedFile("s3://my-bucket/artifact.dat", "artifact");
// after — use local path or ensure plugin is loaded
env.registerCachedFile("file:///opt/artifacts/artifact.dat", "artifact");

// Validate artifact path FileSystem before submission
Path artifactPath = new Path(artifactFilePath);
try {
    FileSystem fs = artifactPath.getFileSystem();
    if (!fs.isDistributedFS()) {
        // local — OK, will be uploaded
    }
} catch (IOException e) {
    throw new IllegalArgumentException("Artifact path '" + artifactFilePath + "' has an unresolvable filesystem scheme", e);
}

try {
    client.submitJob(executionPlan).get();
} catch (ExecutionException e) {
    Throwable cause = ExceptionUtils.stripExecutionException(e);
    if (cause.getMessage().contains("Failed to get the FileSystem of artifact")) {
        // check for missing FS plugin, switch to local path
    }
}

When it happens

Trigger: An artifact registered via DistributedCache uses a path with a scheme like 's3://' or 'hdfs://' but the corresponding FileSystem plugin is not on the client classpath; the artifact path is malformed; the FileSystem factory for the scheme is not registered.

Common situations: Registering a distributed-cache file with an HDFS path but not including flink-hadoop-fs or the S3 plugin JARs in the client lib directory; artifact path uses a custom scheme whose plugin JAR is missing from Flink's lib/ folder; typo in the artifact path scheme.

Related errors

• Failed to serialize ExecutionPlan.
• Failed to submit ExecutionPlan.
• An error occurred while copying the file.
• DistributedCache supports only local files for Collection En
• Java program should be specified a JAR file.

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/e683bc6c6269e218. Report an issue: GitHub.