apache/maven · error · IllegalStateException

The use of the root attribute on the model requires the buil

Error message

The use of the root attribute on the model requires the buildconsumer feature to be active

What it means

Thrown during consumer-POM transformation when the project's model declares the <project root="true"> attribute but the buildconsumer feature is not enabled. The 'root' marker (which lets Maven 4 stop parent resolution at a root module) is only meaningful in consumer-POM processing; with the feature off, Maven refuses the build instead of silently dropping the attribute.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/ConsumerPomArtifactTransformer.java:94

    public void injectTransformedArtifacts(RepositorySystemSession session, MavenProject project) throws IOException {
        if (project.getFile() == null) {
            // If there is no build POM there is no reason to inject artifacts for the consumer POM.
            return;
        }
        if (Features.consumerPom(session.getConfigProperties())) {
            Path buildDir =
                    project.getBuild() != null ? Paths.get(project.getBuild().getDirectory()) : null;
            if (buildDir != null) {
                Files.createDirectories(buildDir);
            }
            Path consumer = buildDir != null
                    ? Files.createTempFile(buildDir, CONSUMER_POM_CLASSIFIER + "-", ".pom")
                    : Files.createTempFile(CONSUMER_POM_CLASSIFIER + "-", ".pom");
            deferDeleteFile(consumer);

            project.addAttachedArtifact(createConsumerPomArtifact(project, consumer, session));
        } else if (project.getModel().getDelegate().isRoot()) {
            throw new IllegalStateException(
                    "The use of the root attribute on the model requires the buildconsumer feature to be active");
        }
    }

    private TransformedArtifact createConsumerPomArtifact(
            MavenProject project, Path consumer, RepositorySystemSession session) {
        Path actual = project.getFile().toPath();
        Path parent = project.getBaseDirectory();
        ModelSource source = new ModelSource() {
            @Override
            public Path getPath() {
                return actual;
            }

            @Override
            public InputStream openStream() throws IOException {
                return Files.newInputStream(actual);
            }

View on GitHub (pinned to e4093d4e12)

Solutions

1. Enable the buildconsumer/consumer-POM feature: build with Maven 4 defaults or add the feature flag (e.g. -Dmaven.consumer.pom=true / enable experimental features) so the attribute is processed
2. Or remove the root attribute from <project> if you do not need the root-resolution behavior
3. If the attribute comes from a parent you cannot change, override/neutralize it in the effective model used by the disabled-feature build
4. Check .mvn/maven.config and CI MAVEN_ARGS for flags that disable the feature

Example fix

<!-- before -->
<project root="true" ...>  <!-- fails when buildconsumer is off -->

<!-- after: drop the attribute, or build with the feature on -->
<project ...>
<!-- and: mvn -Dmaven.consumer.pom=true package -->

// before building, verify feature availability if the model uses root
if (model.isRoot() && !Features.consumerPom(session.getConfigProperties())) {
    throw new IllegalStateException("Remove root='true' or enable the buildconsumer feature");
}

try {
    transformer.transformArtifact(session, project);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("root attribute")) { /* strip root or enable feature, retry */ }
}

When it happens

Trigger: A POM containing root="true" on <project> (or inheriting a model that sets it) built with the consumer POM transformation disabled, e.g. -Dmaven.consumer.pom=false or an experimental-features configuration that turns buildconsumer off; opening a Maven 4 project with an embedder that disables the feature.

Common situations: Setting root="true" on an aggregator POM after reading Maven 4 docs, then building with tooling (older IDE embedder, CI using explicit feature flags) that has buildconsumer disabled; toggling feature flags in .mvn/maven.config and forgetting that root depends on buildconsumer.

Related errors

• The consumer POM for {} cannot be created because the POM co
• The consumer POM for %s cannot be downgraded to model versio
• Duplicate dependency: {}
• Error evaluating plugin parameter expression: ${expression}
• Repository list contains duplicate entries. Each repository

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/e8905efa0f2bdd52. Report an issue: GitHub.