quarkusio/quarkus · error · CodestartStructureException

This file is forbidden in the output-strategy definition: +

Error message

This file is forbidden in the output-strategy definition: + relativePath

What it means

ForbiddenCodestartFileStrategyHandler throws CodestartStructureException if any codestart file matches a relativePath that the output-strategy definition marks as 'forbidden'. The strategy produces no output at all; its whole purpose is to assert that a path is never present in codestart output. Size>0 means some codestart contributed a file at the forbidden path.

Source

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

import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;

import io.quarkus.devtools.codestarts.CodestartStructureException;
import io.quarkus.devtools.codestarts.core.reader.TargetFile;

final class ForbiddenCodestartFileStrategyHandler implements CodestartFileStrategyHandler {
    @Override
    public String name() {
        return "forbidden";
    }

    @Override
    public void process(Path targetDirectory, String relativePath, List<TargetFile> codestartFiles, Map<String, Object> data)
            throws IOException {
        if (codestartFiles.size() > 0) {
            throw new CodestartStructureException("This file is forbidden in the output-strategy definition: " + relativePath);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the file from the offending codestart so it no longer matches the forbidden path
2. Remove or adjust the 'forbidden' entry in the output-strategy definition if the file is now legitimate
3. Exclude the codestart that contributes the forbidden file

Example fix

// before
output-strategy:
  docker-compose.yml: forbidden
  # but codestart still ships docker-compose.yml

// after
# either delete the file from the codestart, or change strategy:
output-strategy:
  docker-compose.yml: merge

boolean hasForbidden = codestartFiles.stream()
    .anyMatch(f -> forbiddenPaths.contains(f.getRelativePath()));
if (hasForbidden) throw new IllegalStateException("Codestart ships a forbidden file");

try {
    handler.process(targetDir, relativePath, codestartFiles, data);
} catch (CodestartStructureException e) {
    if (e.getMessage().startsWith("This file is forbidden")) {
        // locate and remove the offending codestart contribution
    } else throw e;
}

When it happens

Trigger: A codestart being applied contains a file whose relativePath is listed with the 'forbidden' output strategy in the project's output-strategy definition (codestartFiles.size() > 0).

Common situations: Project codestart defines paths it must never receive (e.g. legacy configs) but an included base/extension codestart still ships that file; a typo in the forbidden path is unlikely since the strategy only fires on an actual match.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Target file already exists: + targetPath.toString()
• Multiple files found for path with executable FileStrategy:
• Multiple files found for path with 'fail-on-duplicate' FileS
• Multiple files found for path with 'fail-on-duplicate' FileS
• Unsupported config type: + configType

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