{"record":{"id":"0dba46646fc419b5","repo":"apache/flink","slug":"there-are-no-legal-characters-in-the-file-name","errorCode":null,"errorMessage":"There are no legal characters in the file name","messagePattern":"There are no legal characters in the file name","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/util/FileLock.java","lineNumber":47,"sourceCode":"/** A file lock used for avoiding race condition among multiple threads/processes. */\n@Internal\npublic class FileLock {\n    private static final String TEMP_DIR = System.getProperty(\"java.io.tmpdir\");\n    private final File file;\n    private FileOutputStream outputStream;\n    private java.nio.channels.FileLock lock;\n\n    /**\n     * Initialize a FileLock using a file located at fullPath.\n     *\n     * @param fullPath The path of the locking file\n     */\n    public FileLock(String fullPath) {\n        Preconditions.checkNotNull(fullPath, \"fullPath should not be null\");\n        Path path = Paths.get(fullPath);\n        String normalizedFileName = normalizeFileName(path.getFileName().toString());\n        if (normalizedFileName.isEmpty()) {\n            throw new IllegalArgumentException(\"There are no legal characters in the file name\");\n        }\n        this.file =\n                path.getParent() == null\n                        ? new File(TEMP_DIR, normalizedFileName)\n                        : new File(path.getParent().toString(), normalizedFileName);\n    }\n\n    /**\n     * Initialize a FileLock using a file located at parentDir/fileName.\n     *\n     * @param parentDir The parent dir of the locking file\n     * @param fileName The name of the locking file\n     */\n    public FileLock(String parentDir, String fileName) {\n        Preconditions.checkNotNull(parentDir, \"parentDir should not be null\");\n        Preconditions.checkNotNull(fileName, \"fileName should not be null\");\n        this.file = new File(parentDir, normalizeFileName(fileName));\n    }","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/FileLock.java#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Log/inspect the actual fullPath reaching FileLock and fix the upstream path construction","Validate the file name portion before constructing: non-empty after removing illegal characters, and ideally alphanumeric plus '.', '-', '_'","Sanitize identifiers (job/subtask ids) before embedding them into file names"],"exampleFix":"// before\nnew FileLock(dir + \"/\" + rawId + \".lock\"); // rawId = \"***\"\n\n// after\nString safeId = rawId.replaceAll(\"[^A-Za-z0-9._-]\", \"_\");\nif (safeId.replace(\"_\", \"\").isEmpty()) throw new IllegalArgumentException(\"Bad lock id: \" + rawId);\nnew FileLock(dir + \"/\" + safeId + \".lock\");","handlingStrategy":"validation","validationCode":"String name = Paths.get(fullPath).getFileName().toString();\nString sanitized = name.replaceAll(\"[^A-Za-z0-9._-]\", \"\");\nif (sanitized.isEmpty()) throw new IllegalArgumentException(\"Lock file name has no legal characters: \" + fullPath);","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) and report the offending fullPath back to the caller/config layer — the path itself is the bug.","preventionTips":["Restrict embedded identifiers in file names to [A-Za-z0-9._-]","Unit-test path-building code with adversarial ids before shipping"],"tags":["flink-core","filesystem","validation","file-lock","sanitization"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}