quarkusio/quarkus · error · CodestartStructureException

Target file already exists: + targetPath.toString()

Error message

Target file already exists: + targetPath.toString()

What it means

DockerComposeCodestartFileStrategyHandler throws CodestartStructureException when it is about to write a docker-compose related file but the target file already exists on disk and does not begin with the include-line marker (#/quarkus-include or similar). Codestarts merge docker-compose files via include lines; an existing file that is not an include-merged file would be silently overwritten, so the library refuses. This protects user-authored docker-compose content from being clobbered by a codestart generation.

Source

Thrown at independent-projects/tools/codestarts/src/main/java/io/quarkus/devtools/codestarts/core/strategy/DockerComposeCodestartFileStrategyHandler.java:50

            writeFile(targetDirectory.resolve(filename), targetFile.getContent());

            includes.add(filename);
        }
        data.put(NAME, includes);

        StringBuilder content = new StringBuilder(INCLUDE_LINE_IDENTIFIER);
        for (String include : includes) {
            content.append("  - ").append(include).append("\n");
        }

        final Path targetPath = targetDirectory.resolve("docker-compose.yml");
        writeFile(targetPath, content.toString());
    }

    @Override
    public void writeFile(final Path targetPath, final String content) throws IOException {
        if (Files.exists(targetPath) && !Files.readString(targetPath).startsWith(INCLUDE_LINE_IDENTIFIER)) {
            throw new CodestartStructureException(
                    "Target file already exists: " + targetPath.toString());
        }

        Files.writeString(targetPath, content);
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete or rename the existing docker-compose file at targetPath so the codestart can generate a fresh one
2. Add the expected include-line identifier as the first line of the existing file so the merge strategy treats it as a merged file
3. Back up the existing compose file, let the codestart write a new one, and manually re-apply your customizations

Example fix

// before
docker-compose.yml:
services:
  db: ...

// after
docker-compose.yml:
#/quarkus-include
include: [docker-compose.generated.yml]
services:
  db: ...

Path targetPath = targetDir.resolve("docker-compose.yml");
if (Files.exists(targetPath) && !Files.readString(targetPath).startsWith(INCLUDE_LINE_IDENTIFIER)) {
    throw new IllegalStateException("Existing non-merged docker-compose file at " + targetPath + " — remove or add include line first");
}

try {
    handler.process(targetDir, relativePath, files, data);
} catch (CodestartStructureException e) {
    if (e.getMessage().startsWith("Target file already exists")) {
        // prompt user to remove/rename the existing file or merge manually
    } else throw e;
}

When it happens

Trigger: Running a codestart that includes a docker-compose strategy when targetDirectory already contains a docker-compose.yml (or similar target file) whose content does not start with the include-line identifier.

Common situations: Re-running `quarkus create` or codestart application into a project where docker-compose.yml was previously generated by hand or by an older codestart version that predates the include-line merge format.

Related errors

• File already exists: + targetPath.toString()
• Services have not been started yet
• Services named ${servicesToWaitFor} do not exist, but wait c
• Docker Compose not found. Is ${composeExecutable} on the PAT
• Unsupported port format: ${port}

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