apache/flink · error · IllegalArgumentException

File with name '${name}' is not available. Did you forget to

Error message

File with name '${name}' is not available. Did you forget to register the file?

What it means

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.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/cache/DistributedCache.java:150

    // ------------------------------------------------------------------------

    private final Map<String, Future<Path>> cacheCopyTasks;

    public DistributedCache(Map<String, Future<Path>> cacheCopyTasks) {
        this.cacheCopyTasks = cacheCopyTasks;
    }

    // ------------------------------------------------------------------------

    public File getFile(String name) {
        if (name == null) {
            throw new NullPointerException("name must not be null");
        }

        Future<Path> future = cacheCopyTasks.get(name);
        if (future == null) {
            throw new IllegalArgumentException(
                    "File with name '"
                            + name
                            + "' is not available."
                            + " Did you forget to register the file?");
        }

        try {
            final Path path = future.get();
            URI tmp = path.makeQualified(path.getFileSystem()).toUri();
            return new File(tmp);
        } catch (ExecutionException e) {
            throw new RuntimeException("An error occurred while copying the file.", e.getCause());
        } catch (Exception e) {
            throw new RuntimeException(
                    "Error while getting the file registered under '"
                            + name
                            + "' from the distributed cache",
                    e);

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Register the file on the ExecutionEnvironment with the exact name used in getFile: env.registerCachedFile(path, "model").
2. Double-check spelling/case of the name on both registration and lookup sides.
3. If the file is optional, guard with a check (e.g., track registered names) before calling getFile.

Example fix

// before
// in operator:
getRuntimeContext().getDistributedCache().getFile("model");
// but registration was:
// env.registerCachedFile("/data/weights.bin", "weights");
// after — make names match
env.registerCachedFile("/data/model.bin", "model");
// in operator:
getRuntimeContext().getDistributedCache().getFile("model");

// ensure the name was registered with the exact spelling
env.registerCachedFile("/data/model.bin", "model");
// in operator:
getRuntimeContext().getDistributedCache().getFile("model");

try { cache.getFile(name); }
catch (IllegalArgumentException e) { /* not registered; degrade */ }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• cache file {name}already exists!
• name must not be null
• Failed to get the FileSystem of artifact {artifactFilePath}.
• Name and aggregator must not be null
• An aggregator is already registered under the given name.

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