{"record":{"id":"a51a575a4b93f194","repo":"apache/flink","slug":"distributedcache-supports-only-local-files-for-col","errorCode":null,"errorMessage":"DistributedCache supports only local files for Collection Environments","messagePattern":"DistributedCache supports only local files for Collection Environments","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/operators/CollectionExecutor.java","lineNumber":634,"sourceCode":"        public <T extends Value> T getPreviousIterationAggregate(String name) {\n            return (T) previousAggregates.get(name);\n        }\n    }\n\n    private static final class CompletedFuture implements Future<Path> {\n\n        private final Path result;\n\n        public CompletedFuture(Path entry) {\n            try {\n                LocalFileSystem fs =\n                        (LocalFileSystem) FileSystem.getUnguardedFileSystem(entry.toUri());\n                result =\n                        entry.isAbsolute()\n                                ? new Path(entry.toUri().getPath())\n                                : new Path(fs.getWorkingDirectory(), entry);\n            } catch (Exception e) {\n                throw new RuntimeException(\n                        \"DistributedCache supports only local files for Collection Environments\");\n            }\n        }\n\n        @Override\n        public boolean cancel(boolean mayInterruptIfRunning) {\n            return false;\n        }\n\n        @Override\n        public boolean isCancelled() {\n            return false;\n        }\n\n        @Override\n        public boolean isDone() {\n            return true;\n        }","sourceCodeStart":616,"sourceCodeEnd":652,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/operators/CollectionExecutor.java#L616-L652","documentation":"Thrown by the CompletedFuture inner class constructor in CollectionExecutor when resolving a DistributedCache file path fails. The constructor tries to resolve the path via FileSystem.getUnguardedFileSystem() and cast it to LocalFileSystem; if the path refers to a non-local scheme (e.g., hdfs://, s3://), the cast or resolution throws and the catch block wraps it as a RuntimeException. Collection environments only support local files because they execute in-process without a distributed filesystem.","triggerScenarios":"Registering a DistributedCache file with a non-local URI scheme (hdfs://, s3://, gs://, etc.) and then executing the job with a CollectionEnvironment. The constructor catches any Exception from FileSystem.getUnguardedFileSystem() or the LocalFileSystem cast and throws this generic message.","commonSituations":"A developer registers a cached file via env.registerCachedFile(\"hdfs://namenode/path\", \"name\") and runs locally with CollectionEnvironment. The collection executor cannot access remote filesystems, so it rejects the file. Also triggered if the local file path is invalid or unreadable (though the message would be the same due to the broad catch block).","solutions":["Use only local file paths (file:// or relative paths) when registering cached files with a CollectionEnvironment.","Switch to LocalEnvironment or a mini-cluster if remote file access is needed.","Download the remote file to a local temporary directory before registering it as a cached file for local testing."],"exampleFix":"// before — remote path with collection environment\nenv = new CollectionEnvironment();\nenv.registerCachedFile(\"hdfs://namenode/cache/data.txt\", \"data\");\n// after — local path for collection environment\nenv = new CollectionEnvironment();\nenv.registerCachedFile(\"/tmp/cache/data.txt\", \"data\");","handlingStrategy":"validation","validationCode":"// Validate cached file scheme before registering with CollectionEnvironment\nPath path = new Path(filePath);\nString scheme = path.toUri().getScheme();\nif (scheme != null && !scheme.equals(\"file\")) {\n    throw new IllegalArgumentException(\n        \"CollectionEnvironment only supports local (file://) cached files, got: \" + scheme);\n}\nenv.registerCachedFile(filePath, name);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use only local file paths (file:// or relative) for cached files in CollectionEnvironment.","Switch to LocalEnvironment or mini-cluster if remote filesystem access is required.","Download remote files to a local temp directory before registering them for local testing."],"tags":["distributed-cache","collection-executor","local-files","filesystem","flink-core"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}