apache/maven · error · MavenException

The consumer POM for %s cannot be downgraded to model versio

Error message

The consumer POM for %s cannot be downgraded to model version 4.0.0 because it contains features that require a newer model version. Since consumer POM flattening is disabled, the parent reference is preserved, which requires consumers to resolve the parent POM.
You have the following options to resolve this:
  1. Enable flattening by setting the property 'maven.consumer.pom.flatten=true' to inline parent content and produce a self-contained 4.0.0 consumer POM
  2. Preserve the model version by setting 'preserve.model.version=true' on the <project> element (Maven 4 consumers only)
  3. Remove the features that require a newer model version

What it means

After building a POM-packaged project's consumer POM, DefaultConsumerPomBuilder validates that the result could be downgraded to modelVersion 4.0.0. For packaging 'pom' the artifact IS the parent that Maven 3/Gradle consumers must resolve, so if it still needs a newer model version (and the parent reference is preserved because flattening is off), the build fails: old consumers would not be able to read it.

Source

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

            // When flattening is disabled, treat non-POM projects like parent POMs
            // Apply only basic transformations without flattening dependency management
            // BOMs always need the effective (interpolated) model because transformBom()
            // strips parent and properties — any ${...} references would become dangling.
            // The flatten flag has no semantic effect on BOMs (transformBom always produces
            // a self-contained POM), so we use the same buildBom() path regardless.
            if (isBom) {
                return buildBom(session, project, src);
            } else {
                Model result = buildPom(session, project, src);
                // Validate POM-packaged projects (parent POMs): if the consumer POM cannot be
                // downgraded to 4.0.0, Maven 3 / Gradle cannot resolve the parent.
                // Non-POM projects are consumed as dependencies where unknown elements are
                // ignored, so a higher model version is acceptable (only a warning is logged
                // by transformNonPom/transformPom).
                if (POM_PACKAGING.equals(packaging)
                        && !model.isPreserveModelVersion()
                        && !ModelBuilder.MODEL_VERSION_4_0_0.equals(result.getModelVersion())) {
                    throw new MavenException("""
                            The consumer POM for %s cannot be downgraded to model version 4.0.0 because it contains\
                             features that require a newer model version.\
                             Since consumer POM flattening is disabled, the parent reference is\
                             preserved, which requires consumers to resolve the parent POM.
                            You have the following options to resolve this:
                              1. Enable flattening by setting the property 'maven.consumer.pom.flatten=true'\
                             to inline parent content and produce a self-contained 4.0.0 consumer POM
                              2. Preserve the model version by setting 'preserve.model.version=true'\
                             on the <project> element (Maven 4 consumers only)
                              3. Remove the features that require a newer model version""".formatted(project.getId()));
                }
                return result;
            }
        }
        // Default behavior: flatten the consumer POM
        if (POM_PACKAGING.equals(packaging)) {
            if (isBom) {
                return buildBom(session, project, src);

View on GitHub (pinned to e4093d4e12)

Solutions

Enable flattening: set 'maven.consumer.pom.flatten=true' so parent content is inlined into a self-contained 4.0.0 consumer POM
Or set 'preserve.model.version=true' on <project> if all consumers are Maven 4
Or remove the 4.1+ features from the parent POM so it downgrades cleanly to 4.0.0
If Maven 3 compatibility is required, keep the parent strictly 4.0.0-compatible (flattening on is the usual choice)

Example fix

# before
mvn deploy   # parent POM with 4.1 features, no flatten -> MavenException

# after (in the parent pom.xml properties or .mvn/maven.config)
maven.consumer.pom.flatten=true
mvn deploy

Defensive patterns

Strategy: validation

Validate before calling

// for packaging=pom projects, guard before deploy
if ("pom".equals(model.getPackaging()) && !flattenEnabled && !model.isPreserveModelVersion()) {
    // ensure the transformed model downgrades to 4.0.0, otherwise fail early with guidance
}

Try / catch

catch (MavenException e) {
    if (e.getMessage().contains("cannot be downgraded")) {
        // enable flatten / preserve model version / remove 4.1 features, then rebuild
    }
}

Prevention

Publish parent POMs from a Maven version/feature set compatible with your consumers
Enable flattening for all parent/bom modules in the CI release profile
Smoke-test published parent POMs by building a sample Maven 3 project against them

When it happens

Trigger: A <packaging>pom</packaging> project using 4.1+ model features (mixins, subprojects, new dependency attributes...) where the transformed consumer POM's modelVersion is not 4.0.0, while both 'maven.consumer.pom.flatten' and 'preserve.model.version' are disabled. The check at buildPom's call site throws MavenException listing three remediation options.

Common situations: Publishing a Maven 4 parent/BOM with new syntax that Maven 3 users consume; enabling consumer POM generation but forgetting flattening for parent-POM projects; mixing 4.x-only features into a parent inherited by 3.x builds.

Related errors

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