{"record":{"id":"e8905efa0f2bdd52","repo":"apache/maven","slug":"the-use-of-the-root-attribute-on-the-model-require","errorCode":null,"errorMessage":"The use of the root attribute on the model requires the buildconsumer feature to be active","messagePattern":"The use of the root attribute on the model requires the buildconsumer feature to be active","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/ConsumerPomArtifactTransformer.java","lineNumber":94,"sourceCode":"    public void injectTransformedArtifacts(RepositorySystemSession session, MavenProject project) throws IOException {\n        if (project.getFile() == null) {\n            // If there is no build POM there is no reason to inject artifacts for the consumer POM.\n            return;\n        }\n        if (Features.consumerPom(session.getConfigProperties())) {\n            Path buildDir =\n                    project.getBuild() != null ? Paths.get(project.getBuild().getDirectory()) : null;\n            if (buildDir != null) {\n                Files.createDirectories(buildDir);\n            }\n            Path consumer = buildDir != null\n                    ? Files.createTempFile(buildDir, CONSUMER_POM_CLASSIFIER + \"-\", \".pom\")\n                    : Files.createTempFile(CONSUMER_POM_CLASSIFIER + \"-\", \".pom\");\n            deferDeleteFile(consumer);\n\n            project.addAttachedArtifact(createConsumerPomArtifact(project, consumer, session));\n        } else if (project.getModel().getDelegate().isRoot()) {\n            throw new IllegalStateException(\n                    \"The use of the root attribute on the model requires the buildconsumer feature to be active\");\n        }\n    }\n\n    private TransformedArtifact createConsumerPomArtifact(\n            MavenProject project, Path consumer, RepositorySystemSession session) {\n        Path actual = project.getFile().toPath();\n        Path parent = project.getBaseDirectory();\n        ModelSource source = new ModelSource() {\n            @Override\n            public Path getPath() {\n                return actual;\n            }\n\n            @Override\n            public InputStream openStream() throws IOException {\n                return Files.newInputStream(actual);\n            }","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/ConsumerPomArtifactTransformer.java#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Or remove the root attribute from <project> if you do not need the root-resolution behavior","If the attribute comes from a parent you cannot change, override/neutralize it in the effective model used by the disabled-feature build","Check .mvn/maven.config and CI MAVEN_ARGS for flags that disable the feature"],"exampleFix":"<!-- before -->\n<project root=\"true\" ...>  <!-- fails when buildconsumer is off -->\n\n<!-- after: drop the attribute, or build with the feature on -->\n<project ...>\n<!-- and: mvn -Dmaven.consumer.pom=true package -->","handlingStrategy":"validation","validationCode":"// before building, verify feature availability if the model uses root\nif (model.isRoot() && !Features.consumerPom(session.getConfigProperties())) {\n    throw new IllegalStateException(\"Remove root='true' or enable the buildconsumer feature\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    transformer.transformArtifact(session, project);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"root attribute\")) { /* strip root or enable feature, retry */ }\n}","preventionTips":["Keep .mvn/maven.config feature flags consistent across all modules and CI jobs","Do not set root='true' in POMs built by tooling with buildconsumer disabled","Document feature-flag dependencies next to POM attributes that require them"],"tags":["maven","consumer-pom","buildconsumer","feature-flag","pom-attribute"],"backgroundTag":"feature-required-not-enabled","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}