apache/flink · error · RuntimeException

Error while getting the file registered under '${name}' from

Error message

Error while getting the file registered under '${name}' from the distributed cache

What it means

Thrown by DistributedCache.getFile() when future.get() throws an exception that is NOT an ExecutionException — typically an InterruptedException. This means the calling thread was interrupted while waiting for the distributed-cache file copy to complete. The RuntimeException wraps the original exception and includes the name the file was registered under.

Source

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

        }

        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);
        }
    }

    // ------------------------------------------------------------------------
    //  Utilities to read/write cache files from/to the configuration
    // ------------------------------------------------------------------------

    public static void writeFileInfoToConfig(
            String name, DistributedCacheEntry e, Configuration conf) {
        int num = conf.get(getIntConfigOption(CACHE_FILE_NUM), 0) + 1;
        conf.set(getIntConfigOption(CACHE_FILE_NUM), num);
        conf.setString(CACHE_FILE_NAME + num, name);
        conf.setString(CACHE_FILE_PATH + num, e.filePath);
        conf.set(

View on GitHub (pinned to 2f3c205e92)

Solutions

Check whether the job was cancelled or the task was concurrently failed — this exception is often a side effect of teardown, not the primary fault.
If using large cached files, pre-stage them or use a smaller file to reduce copy latency so the thread is less likely to be interrupted mid-copy.
Restore the interrupted status by calling Thread.currentThread().interrupt() in your catch block if you handle this exception, to respect Java interruption conventions.
Inspect the original exception (the 'e' parameter) for the true interruption source.

Example fix

// before
File cached = getRuntimeContext().getDistributedCache().getFile("lookup");

// after — handle interruption gracefully
try {
    File cached = getRuntimeContext().getDistributedCache().getFile("lookup");
} catch (RuntimeException e) {
    if (e.getCause() instanceof InterruptedException) {
        Thread.currentThread().interrupt();
        log.warn("Interrupted while fetching distributed cache file 'lookup'");
        return;
    }
    throw e;
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    File cachedFile = getRuntimeContext().getDistributedCache().getFile("myFile");
} catch (RuntimeException e) {
    if (e.getCause() instanceof InterruptedException) {
        Thread.currentThread().interrupt();
        log.warn("Thread interrupted while fetching distributed cache file");
        return; // or handle gracefully
    }
    throw e;
}

Prevention

Keep cached files small to reduce the window for interruption during copy.
Always restore interrupt status (Thread.currentThread().interrupt()) if you catch InterruptedException.
Check job health and cancellation signals if this occurs frequently — it may indicate systemic cancellation.

When it happens

Trigger: RuntimeContext.getDistributedCache().getFile(name) is called and the thread is interrupted during Future.get(). This can happen during job cancellation, task failure, or when the runtime cancels running tasks.

Common situations: Job cancellation while a task is still copying cached files. A TaskManager slot preemption or timeout that interrupts the task thread. Heavy load causing the file copy to take longer than a thread-interrupt timeout.

Related errors

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