{"record":{"id":"1efe049a9c207b06","repo":"apache/flink","slug":"failed-to-create-the-parent-directory","errorCode":null,"errorMessage":"Failed to create the parent directory: {}","messagePattern":"Failed to create the parent directory: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/core/fs/local/LocalRecoverableWriter.java","lineNumber":54,"sourceCode":"/** A {@link RecoverableWriter} for the {@link LocalFileSystem}. */\n@Internal\npublic class LocalRecoverableWriter implements RecoverableWriter {\n\n    private final LocalFileSystem fs;\n\n    public LocalRecoverableWriter(LocalFileSystem fs) {\n        this.fs = checkNotNull(fs);\n    }\n\n    @Override\n    public RecoverableFsDataOutputStream open(Path filePath) throws IOException {\n        final File targetFile = fs.pathToFile(filePath);\n        final File tempFile = generateStagingTempFilePath(targetFile);\n\n        // try to create the parent\n        final File parent = tempFile.getParentFile();\n        if (parent != null && !parent.mkdirs() && !parent.exists()) {\n            throw new IOException(\"Failed to create the parent directory: \" + parent);\n        }\n\n        return new LocalRecoverableFsDataOutputStream(targetFile, tempFile);\n    }\n\n    @Override\n    public RecoverableFsDataOutputStream recover(ResumeRecoverable recoverable) throws IOException {\n        if (recoverable instanceof LocalRecoverable) {\n            return new LocalRecoverableFsDataOutputStream((LocalRecoverable) recoverable);\n        } else {\n            throw new IllegalArgumentException(\n                    \"LocalFileSystem cannot recover recoverable for other file system: \"\n                            + recoverable);\n        }\n    }\n\n    @Override\n    public boolean requiresCleanupOfRecoverableState() {","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/core/fs/local/LocalRecoverableWriter.java#L36-L72","documentation":"Thrown by LocalRecoverableWriter.open when the parent directory of the staging temp file cannot be created. The writer calls parent.mkdirs() and, if that returns false AND the parent still does not exist, throws this IOException. This protects against writing to a path whose parent is missing and cannot be auto-created (e.g. permission denied, read-only filesystem, or an intermediate path component is a file).","triggerScenarios":"Opening a LocalRecoverableWriter for an output Path whose parent directory does not exist and cannot be created; the parent path is occupied by a regular file; insufficient filesystem permissions to create directories; the filesystem is mounted read-only.","commonSituations":"Configuring a file sink with an output path whose parent directory was never created; running in a container/sandbox where the output mount is read-only; path typos pointing to a non-existent base directory; concurrent cleanup that removed the parent between checks.","solutions":["Verify the output path's parent directory exists and is writable: ensure the base directory is created before the job starts or pre-create it in your deployment.","Check filesystem permissions for the user running the TaskManager process.","If running in a container, confirm the volume is mounted read-write and the mount point exists.","Avoid paths that collide with existing files for any intermediate component."],"exampleFix":"// before\nPath out = new Path(\"/data/sink/output.parquet\");\nwriter.open(out);\n\n// after — pre-create parent\nnew File(out.getPath()).getParentFile().mkdirs();\nwriter.open(out);","handlingStrategy":"validation","validationCode":"File parent = new File(outputPath.getPath()).getParentFile();\nif (parent != null && !parent.exists() && !parent.mkdirs()) {\n    throw new IOException(\"Cannot create output parent directory: \" + parent);\n}","typeGuard":null,"tryCatchPattern":"try {\n    writer.open(filePath);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"parent directory\")) {\n        // check permissions, mount type, path validity\n    }\n    throw e;\n}","preventionTips":["Pre-create the output base directory in your deployment scripts.","Verify the TaskManager process user has write permission on the output path.","Confirm container volume mounts are read-write before starting the job."],"tags":["local-filesystem","filesystem-io","permissions","sink"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}