quarkusio/quarkus · error · CodestartStructureException

codestartFiles must not be null or empty

Error message

codestartFiles must not be null or empty

What it means

CodestartFileStrategyHandler.checkNotEmptyCodestartFiles is a shared guard used by file strategy handlers before processing conflict resolution. It throws when the list of candidate TargetFiles for a path is null or empty, which would make strategy processing meaningless. This indicates an internal inconsistency in collected codestart files rather than user data format.

Source

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

                    new AppendCodestartFileStrategyHandler(),
                    new ContentMergeCodestartFileStrategyHandler(),
                    new ExecutableFileStrategyHandler(),
                    new ReplaceCodestartFileStrategyHandler(),
                    new ForbiddenCodestartFileStrategyHandler(),
                    new SmartConfigMergeCodestartFileStrategyHandler(),
                    new SmartPomMergeCodestartFileStrategyHandler(),
                    new SmartPackageFileStrategyHandler(),
                    new DockerComposeCodestartFileStrategyHandler())
            .collect(Collectors.toMap(CodestartFileStrategyHandler::name, Function.identity()));

    String name();

    void process(Path targetDirectory, String relativePath, List<TargetFile> codestartFiles, Map<String, Object> data)
            throws IOException;

    default void checkNotEmptyCodestartFiles(List<TargetFile> codestartFiles) {
        if (codestartFiles == null || codestartFiles.isEmpty()) {
            throw new CodestartStructureException("codestartFiles must not be null or empty");
        }
    }

    default void checkTargetDoesNotExist(Path targetPath) {
        if (Files.exists(targetPath)) {
            throw new CodestartStructureException(
                    "Target file already exists: " + targetPath.toString());
        }
    }

    default void createDirectories(Path targetPath) throws IOException {
        Files.createDirectories(targetPath.getParent());
    }

    default void writeFile(final Path targetPath, final String content) throws IOException {
        if (!SKIP_FILE_IDENTIFIER.equals(content)) {
            Files.write(targetPath, content.getBytes(StandardCharsets.UTF_8));
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Call checkNotEmptyCodestartFiles(files) at the top of your custom handler's process() and skip/no-op when empty
2. Investigate why the file collection step produced an empty list for that relative path (filters, selectors)
3. Update to a Quarkus version fixing the strategy that generated empty file lists

Example fix

// before
@Override
public void process(...) throws IOException {
    Path target = targetDirectory.resolve(relativePath);
    Files.write(target, codestartFiles.get(0).getContent().getBytes());
}
// after
@Override
public void process(...) throws IOException {
    checkNotEmptyCodestartFiles(codestartFiles);
    Path target = targetDirectory.resolve(relativePath);
    Files.write(target, codestartFiles.get(0).getContent().getBytes());
}

if (files == null || files.isEmpty()) return; // skip handler invocation

try { handler.process(dir, rel, files, data); }
catch (CodestartStructureException e) {
    if ("codestartFiles must not be null or empty".equals(e.getMessage())) { /* guard handler */ }
    else throw e;
}

When it happens

Trigger: A custom or built-in strategy handler invokes process/check with no files collected for a given relative path during generation; upstream file collection returned nothing for a filter match.

Common situations: Custom CodestartFileStrategyHandler implementations forgetting the empty-list guard; codestart selectors matching a strategy but producing zero files; bugs in file reader chains.

Related errors

• Unknown item type: ${otherItem.getClass()}
• Unknown item type: ${otherItem.getClass()}
• Multiple listeners returned discovery root elements for: ${d
• No listeners returned a discovery root element
• Could not find registered EnumDefinition for ${name}

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