{"record":{"id":"f70f0873ad0b12c2","repo":"apache/flink","slug":"cache-file-name-already-exists","errorCode":null,"errorMessage":"cache file {name}already exists!","messagePattern":"cache file (.+?)already exists!","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/Plan.java","lineNumber":342,"sourceCode":"    @Override\n    public void accept(Visitor<Operator<?>> visitor) {\n        for (GenericDataSinkBase<?> sink : this.sinks) {\n            sink.accept(visitor);\n        }\n    }\n\n    /**\n     * Register cache files at program level.\n     *\n     * @param entry contains all relevant information\n     * @param name user defined name of that file\n     * @throws java.io.IOException\n     */\n    public void registerCachedFile(String name, DistributedCacheEntry entry) throws IOException {\n        if (!this.cacheFile.containsKey(name)) {\n            this.cacheFile.put(name, entry);\n        } else {\n            throw new IOException(\"cache file \" + name + \"already exists!\");\n        }\n    }\n\n    /**\n     * Return the registered cached files.\n     *\n     * @return Set of (name, filePath) pairs\n     */\n    public Set<Entry<String, DistributedCacheEntry>> getCachedFiles() {\n        return this.cacheFile.entrySet();\n    }\n\n    public int getMaximumParallelism() {\n        MaxDopVisitor visitor = new MaxDopVisitor();\n        accept(visitor);\n        return Math.max(visitor.maxDop, this.defaultParallelism);\n    }\n","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/Plan.java#L324-L360","documentation":"Thrown by Plan.registerCachedFile when a cache file is registered twice under the same name. The Plan keeps a Map of distributed-cache entries keyed by name; registering a duplicate would silently overwrite the first file, so the API rejects it with an IOException. Note the message has a missing space ('name + \"already exists!\"') but the cause is unambiguous.","triggerScenarios":"Calling registerCachedFile(name, entry) twice with the same name on one Plan; iterating a config that lists the same file under one name; a library that auto-registers a file a user also registered manually.","commonSituations":"Registering the same distributed-cache resource (e.g., a model file, lookup table) in multiple operator setup methods; merging configs from sub-modules that both register 'weights.bin'.","solutions":["Guard with getCachedFiles()/contains check before registering, or use a Set of names already added.","Centralize cache-file registration in one place in your program setup to avoid double-registration across operators.","If a file may legitimately be reused, register once at program assembly time and reference the name from all operators."],"exampleFix":"// before\nplan.registerCachedFile(\"model\", entry1);\nplan.registerCachedFile(\"model\", entry2);\n// after\nSet<String> names = plan.getCachedFiles().stream()\n    .map(Map.Entry::getKey).collect(Collectors.toSet());\nif (!names.contains(\"model\")) {\n    plan.registerCachedFile(\"model\", entry1);\n}","handlingStrategy":"validation","validationCode":"Set<String> names = plan.getCachedFiles().stream()\n    .map(Map.Entry::getKey).collect(Collectors.toSet());\nif (!names.contains(name)) {\n    plan.registerCachedFile(name, entry);\n}","typeGuard":null,"tryCatchPattern":"try { plan.registerCachedFile(name, entry); }\ncatch (IOException e) { /* duplicate; ignore or update */ }","preventionTips":["Centralize cache-file registration in one setup method.","Namespace names per operator to avoid collisions.","Track registered names in a Set and check before registering."],"tags":["distributed-cache","plan","duplicate","registration"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}