{"record":{"id":"381b98ee578a696c","repo":"apache/flink","slug":"file-with-name-name-is-not-available-did-you","errorCode":null,"errorMessage":"File with name '${name}' is not available. Did you forget to register the file?","messagePattern":"File with name '(.+?)' is not available\\. Did you forget to register the file\\?","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/cache/DistributedCache.java","lineNumber":150,"sourceCode":"\n    // ------------------------------------------------------------------------\n\n    private final Map<String, Future<Path>> cacheCopyTasks;\n\n    public DistributedCache(Map<String, Future<Path>> cacheCopyTasks) {\n        this.cacheCopyTasks = cacheCopyTasks;\n    }\n\n    // ------------------------------------------------------------------------\n\n    public File getFile(String name) {\n        if (name == null) {\n            throw new NullPointerException(\"name must not be null\");\n        }\n\n        Future<Path> future = cacheCopyTasks.get(name);\n        if (future == null) {\n            throw new IllegalArgumentException(\n                    \"File with name '\"\n                            + name\n                            + \"' is not available.\"\n                            + \" Did you forget to register the file?\");\n        }\n\n        try {\n            final Path path = future.get();\n            URI tmp = path.makeQualified(path.getFileSystem()).toUri();\n            return new File(tmp);\n        } catch (ExecutionException e) {\n            throw new RuntimeException(\"An error occurred while copying the file.\", e.getCause());\n        } catch (Exception e) {\n            throw new RuntimeException(\n                    \"Error while getting the file registered under '\"\n                            + name\n                            + \"' from the distributed cache\",\n                    e);","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/cache/DistributedCache.java#L132-L168","documentation":"Thrown by DistributedCache.getFile when no cache file was registered under the requested name. The cacheCopyTasks map only contains entries that were registered on the program (ExecutionEnvironment.registerCachedFile) and shipped to the task; asking for an unregistered name means the registration step was skipped or the name doesn't match. The message hints at the usual cause: forgetting to register.","triggerScenarios":"Calling getFile(\"model\") when the program registered the file under a different name (e.g., \"weights\") or never registered it; typos between registration and lookup; registering on the wrong environment instance.","commonSituations":"Operator looks up a cache file that was supposed to be registered in main() but the registration was conditional/removed; name mismatch after refactor; tests that run an operator without the full program setup.","solutions":["Register the file on the ExecutionEnvironment with the exact name used in getFile: env.registerCachedFile(path, \"model\").","Double-check spelling/case of the name on both registration and lookup sides.","If the file is optional, guard with a check (e.g., track registered names) before calling getFile."],"exampleFix":"// before\n// in operator:\ngetRuntimeContext().getDistributedCache().getFile(\"model\");\n// but registration was:\n// env.registerCachedFile(\"/data/weights.bin\", \"weights\");\n// after — make names match\nenv.registerCachedFile(\"/data/model.bin\", \"model\");\n// in operator:\ngetRuntimeContext().getDistributedCache().getFile(\"model\");","handlingStrategy":"validation","validationCode":"// ensure the name was registered with the exact spelling\nenv.registerCachedFile(\"/data/model.bin\", \"model\");\n// in operator:\ngetRuntimeContext().getDistributedCache().getFile(\"model\");","typeGuard":null,"tryCatchPattern":"try { cache.getFile(name); }\ncatch (IllegalArgumentException e) { /* not registered; degrade */ }","preventionTips":["Use identical name strings on registration and lookup.","Register cache files once in main() before job submission.","Cross-check names during code review and tests."],"tags":["distributed-cache","registration","task","name-mismatch"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}