apache/flink · error · NullPointerException

name must not be null

Error message

name must not be null

What it means

Thrown by DistributedCache.getFile(name) when name is null. In a task, getFile resolves a previously registered distributed-cache file by its logical name; null has no mapping and would NPE in the map lookup, so the API rejects it up front. It indicates a caller bug — the name should come from the operator's registered cache entries.

Source

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

                    + ", blobKey="
                    + Arrays.toString(blobKey)
                    + '}';
        }
    }

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

    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) {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Ensure the name passed to getFile matches a name previously registered via registerCachedFile on the ExecutionEnvironment/Plan.
2. Null-check the name variable before calling getFile and surface a clear error pointing at the missing registration.
3. Source cache names from a fixed, validated set rather than runtime-computed strings.

Example fix

// before
File f = getRuntimeContext().getDistributedCache().getFile(cacheName);
// after
if (cacheName == null) {
    throw new IllegalStateException("cache file name not configured for this operator");
}
File f = getRuntimeContext().getDistributedCache().getFile(cacheName);

Objects.requireNonNull(name, "cache file name");
getRuntimeContext().getDistributedCache().getFile(name);

When it happens

Trigger: Calling getRuntimeContext().getDistributedCache().getFile(null); passing a config-derived name that resolved to null.

Common situations: Operator open() methods that look up a cache file via a field that was never set; generic code that iterates cache names where one entry had a null key.

Related errors

• File with name '${name}' is not available. Did you forget to
• Failed to get the FileSystem of artifact {artifactFilePath}.
• The collection contains a null element
• The collection contains a null element
• Hadoop input split must not be null

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