quarkusio/quarkus · error · IOException

Failed to create the project directory: + targetDirectory

Error message

Failed to create the project directory: + targetDirectory

What it means

CodestartProcessor.checkTargetDir() throws IOException('Failed to create the project directory: <targetDirectory>') when the target directory does not exist and File.mkdirs() returns false — i.e. the directory (including parents) could not be created, usually due to permissions or an invalid path.

Source

Thrown at independent-projects/tools/codestarts/src/main/java/io/quarkus/devtools/codestarts/core/CodestartProcessor.java:66

    }

    void process(final CodestartResource projectResource, final Codestart codestart) {
        log.debug("processing codestart '%s'...", codestart.getName());
        addBuiltinData();
        codestart.use(l -> {
            final Map<String, Object> finalData = CodestartData.buildCodestartData(codestart, languageName, data);
            log.debug("codestart data: %s", finalData);
            Stream.of(BASE_LANGUAGE, languageName)
                    .filter(l::dirExists)
                    .forEach(languageDir -> processLanguageDir(projectResource, l, languageDir, finalData));
        });
    }

    public void checkTargetDir() throws IOException {
        if (!Files.exists(targetDirectory)) {
            boolean mkdirStatus = targetDirectory.toFile().mkdirs();
            if (!mkdirStatus) {
                throw new IOException("Failed to create the project directory: " + targetDirectory);
            }
            return;
        }
        if (!Files.isDirectory(targetDirectory)) {
            throw new IOException("Project path needs to point to a directory: " + targetDirectory);
        }
        final String[] files = targetDirectory.toFile().list();
        if (files != null && files.length > 0) {
            throw new IOException("You can't create a project when the directory is not empty: " + targetDirectory);
        }
    }

    public void writeFiles() throws IOException {
        for (Map.Entry<String, List<TargetFile>> e : files.entrySet()) {
            final String relativePath = e.getKey();
            final CodestartFileStrategyHandler strategy = getStrategy(relativePath).orElse(getSelectedDefaultStrategy());
            log.debug("processing file '%s' with strategy %s", relativePath, strategy.name());
            strategy.process(targetDirectory, relativePath, e.getValue(), data);

View on GitHub (pinned to e1c734241f)

Solutions

Check and fix write permissions on the parent directory (e.g. chown/chmod or choose another location).
Verify the target path is valid and its parent exists / is writable.
Create the directory manually beforehand if the generator runs in a restricted environment.

Example fix

// before
mkdirs fails on /root/projects (no permission)
// after
code.quarkus.io target: /home/user/projects/my-app  (writable location)

Defensive patterns

Strategy: validation

Validate before calling

Path target = Path.of(dest);
Path parent = target.toAbsolutePath().getParent();
if (parent == null || !Files.isWritable(parent)) {
    throw new IllegalArgumentException("Cannot create project: parent not writable: " + parent);
}

Try / catch

try {
    processor.generateProject(...);
} catch (IOException e) {
    if (e.getMessage().startsWith("Failed to create the project directory")) {
        logger.error("Check permissions/validity of: " + targetDir);
    }
    throw e;
}

Prevention

Verify write permissions on the destination parent before generating.
Avoid system/protected directories as generation targets.
Pre-create the target directory with correct ownership in CI/containers.

When it happens

Trigger: Project generation into a path where mkdirs() fails: no write permission on the parent, path is on a read-only filesystem, or the path is invalid/already exists as a file created concurrently.

Common situations: Generating a project into a protected system location; running the CLI as a user without rights on the target parent; typoed or overly long paths on Windows.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/3fd85b0238fecdaf. Report an issue: GitHub.