apache/seatunnel · error · IOException

create(): Mkdirs failed to create: ${parent}

Error message

create(): Mkdirs failed to create: ${parent}

What it means

SeaTunnelFTPFileSystem.create() ensures the parent directory of the target path exists by calling mkdirs(client, parent, ...). If parent is null or mkdirs fails, it disconnects and throws IOException('create(): Mkdirs failed to create: <parent>').

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-ftp/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/ftp/system/SeaTunnelFTPFileSystem.java:369

        try {
            status = getFileStatus(client, file);
        } catch (FileNotFoundException fnfe) {
            status = null;
        }
        if (status != null) {
            if (overwrite && !status.isDirectory()) {
                delete(client, file, false);
            } else {
                disconnect(client);
                throw new FileAlreadyExistsException("File already exists: " + file);
            }
        }

        Path parent = absolute.getParent();
        if (parent == null || !mkdirs(client, parent, FsPermission.getDirDefault())) {
            parent = (parent == null) ? new Path("/") : parent;
            disconnect(client);
            throw new IOException("create(): Mkdirs failed to create: " + parent);
        }
        client.allocate(bufferSize);
        // Change to parent directory on the server. Only then can we write to the
        // file on the server by opening up an OutputStream. As a side effect the
        // working directory on the server is changed to the parent directory of the
        // file. The FTP client connection is closed when close() is called on the
        // FSDataOutputStream.
        client.changeWorkingDirectory(parent.toUri().getPath());
        FSDataOutputStream fos =
                new FSDataOutputStream(client.storeFileStream(file.getName()), statistics) {
                    @Override
                    public void close() throws IOException {
                        super.close();
                        if (!client.isConnected()) {
                            throw new FTPException("Client not connected");
                        }
                        boolean cmdCompleted = client.completePendingCommand();
                        disconnect(client);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Pre-create the parent directories manually on the FTP server or grant the FTP user write/create permission there
2. Verify no regular file exists with the same name as one of the parent path components
3. Check the FTP server logs for the MKD command reply to see the exact server-side failure
4. Confirm the path layout matches the server's root/home directory semantics

Example fix

// before
fs.create(new Path("ftp://host/out/2024/09/result.csv")) // /out/2024 not writable by ftp user
// after
# grant write perms or pre-create: mkdir -p /out/2024/09 on the server with correct ownership

// Preflight: ensure parent dir exists or can be created via a plain FTP client
FTPClient c = connect();
Path parent = path.getParent();
boolean ok = parent == null || c.changeWorkingDirectory(parent.toUri().getPath());
disconnect(c);
if (!ok) throw new IllegalStateException("Parent not writable/unreachable on FTP server: " + parent);

try {
    return fs.create(path);
} catch (IOException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("create(): Mkdirs failed")) {
        throw new IllegalStateException("Cannot create parent dir " + path.getParent()
            + " — check FTP user write permissions and path components", e);
    }
    throw e;
}

When it happens

Trigger: Calling create(file) where the parent directory cannot be created on the FTP server — server-side permission denial on the parent path, path component conflict (a file exists with the directory's name), or an unresolvable/null parent.

Common situations: FTP account lacks write permission on the output directory; output path typos creating deep nonexistent trees; a file occupies one of the path components so mkdir fails; FTP server enforces a chroot/home prefix the absolute path ignores.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Failed to change working directory to %s, FTP reply code: %d
• Couldn't create directory %s.
• Invalid host specified
• Invalid user/password specified
• Path ${file} is a directory.

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/317e4b55122478a1. Report an issue: GitHub.