apache/flink · error · FlinkRuntimeException

Failed to create parent(s) for given base dir

Error message

Failed to create parent(s) for given base dir: %s

What it means

Thrown when FileUtils.forceMkdirParent fails while creating parent directories for a base directory during artifact fetching. The method createMissingParents is called to ensure the artifact storage directory exists. The FlinkRuntimeException wraps the original exception and includes the base dir path.

Solutions

1. Ensure the artifact storage directory's parent is writable: 'ls -ld <parent>'.
2. Set the artifact directory to a writable location (e.g., a mounted emptyDir in K8s).
3. Remove any file blocking directory creation at the conflicting path.
4. Check disk space and inode availability on the target volume.

Example fix

# before: read-only parent directory
ls -ld /opt/flink/artifacts
# drwxr-xr-x root root (not writable by flink user)

# after: use a writable directory
mkdir -p /data/flink/artifacts
chown flink:flink /data/flink/artifacts
# set artifact directory config to /data/flink/artifacts

File parent = baseDir.getAbsoluteFile().getParentFile();
if (parent != null && (!parent.exists() || !parent.canWrite())) {
    throw new IllegalStateException(
        "Cannot create parents for " + baseDir + ": parent not writable: " + parent);
}

try {
    ArtifactUtils.createMissingParents(baseDir);
} catch (FlinkRuntimeException e) {
    if (e.getMessage().contains("Failed to create parent(s)")) {
        // check permissions and disk space on parent
    }
    throw e;
}

When it happens

Trigger: Calling ArtifactUtils.createMissingParents(baseDir) when the parent of baseDir cannot be created — due to permissions, a file (not directory) existing in the path, disk full, or a read-only filesystem.

Common situations: Container with a read-only volume mounted at the artifact path, insufficient permissions on the parent directory, or a path conflict where a file exists where a directory is expected.

Related errors

• An I/O error occurred while creating temporary file to…
• Failed to get metadata for key
• Failed to list contents of
• An error occurred while copying the file.
• Compaction file not exist

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

Appendix: source

Thrown at flink-clients/src/main/java/org/apache/flink/client/program/artifact/ArtifactUtils.java:49

public class ArtifactUtils {

    private static final Logger LOG = LoggerFactory.getLogger(ArtifactUtils.class);

    /**
     * Creates missing parent directories for the given {@link File} if there are any. Does nothing
     * otherwise.
     *
     * @param baseDir base dir to create parents for
     */
    public static synchronized void createMissingParents(File baseDir) {
        checkNotNull(baseDir, "Base dir has to be provided.");

        if (!baseDir.exists()) {
            try {
                FileUtils.forceMkdirParent(baseDir);
                LOG.info("Created parents for base dir: {}", baseDir);
            } catch (Exception e) {
                throw new FlinkRuntimeException(
                        String.format("Failed to create parent(s) for given base dir: %s", baseDir),
                        e);
            }
        }
    }

    private ArtifactUtils() {
        throw new UnsupportedOperationException("This class should never be instantiated.");
    }
}

View on GitHub (pinned to 2f3c205e92)