apache/flink · error · IllegalArgumentException

There are no legal characters in the file name

Error message

There are no legal characters in the file name

What it means

Thrown by the FileLock constructor when the file name, after normalizeFileName() strips disallowed characters, is empty. FileLock (used to guard concurrent access to local dirs, e.g. in the local recovery cache) derives a lock file name from the user-supplied path and refuses names made entirely of illegal characters.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/FileLock.java:47

/** A file lock used for avoiding race condition among multiple threads/processes. */
@Internal
public class FileLock {
    private static final String TEMP_DIR = System.getProperty("java.io.tmpdir");
    private final File file;
    private FileOutputStream outputStream;
    private java.nio.channels.FileLock lock;

    /**
     * Initialize a FileLock using a file located at fullPath.
     *
     * @param fullPath The path of the locking file
     */
    public FileLock(String fullPath) {
        Preconditions.checkNotNull(fullPath, "fullPath should not be null");
        Path path = Paths.get(fullPath);
        String normalizedFileName = normalizeFileName(path.getFileName().toString());
        if (normalizedFileName.isEmpty()) {
            throw new IllegalArgumentException("There are no legal characters in the file name");
        }
        this.file =
                path.getParent() == null
                        ? new File(TEMP_DIR, normalizedFileName)
                        : new File(path.getParent().toString(), normalizedFileName);
    }

    /**
     * Initialize a FileLock using a file located at parentDir/fileName.
     *
     * @param parentDir The parent dir of the locking file
     * @param fileName The name of the locking file
     */
    public FileLock(String parentDir, String fileName) {
        Preconditions.checkNotNull(parentDir, "parentDir should not be null");
        Preconditions.checkNotNull(fileName, "fileName should not be null");
        this.file = new File(parentDir, normalizeFileName(fileName));
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Log/inspect the actual fullPath reaching FileLock and fix the upstream path construction
2. Validate the file name portion before constructing: non-empty after removing illegal characters, and ideally alphanumeric plus '.', '-', '_'
3. Sanitize identifiers (job/subtask ids) before embedding them into file names

Example fix

// before
new FileLock(dir + "/" + rawId + ".lock"); // rawId = "***"

// after
String safeId = rawId.replaceAll("[^A-Za-z0-9._-]", "_");
if (safeId.replace("_", "").isEmpty()) throw new IllegalArgumentException("Bad lock id: " + rawId);
new FileLock(dir + "/" + safeId + ".lock");

String name = Paths.get(fullPath).getFileName().toString();
String sanitized = name.replaceAll("[^A-Za-z0-9._-]", "");
if (sanitized.isEmpty()) throw new IllegalArgumentException("Lock file name has no legal characters: " + fullPath);

catch (IllegalArgumentException e) and report the offending fullPath back to the caller/config layer — the path itself is the bug.

When it happens

Trigger: Constructing new FileLock(fullPath) where the file-name portion consists only of characters the normalizer removes (e.g. `???`, `***`, exotic punctuation), so the sanitized name has zero length. A normal name like `my.lock` never triggers this.

Common situations: Programmatically built lock paths where a variable (job id, task id) resolved to illegal-only content; placeholder or test paths like `///` or `***.lock`; encoding issues producing stripped characters.

Related errors

• {directory} is not a directory
• {directory} is not a directory but a regular file
• DistributedCache supports only local files for Collection En
• The output size cannot be smaller than zero.
• The output cardinality cannot be smaller than zero.

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