Skip to content
Choose a tag to compare


Choose a tag to compare


  • Make use of constructor arguments when instantiating mapping targets (#73) - Also supports Java 14 records and Kotlin Data classes
  • Support using "." for targeting current target object (#1406)
  • Support value mapping between String and Enum (#1557)
  • Support @Mapping in meta annotation (#807)
  • Support Gradle incremental annotation processing feature (#1420)
  • User control over mapping features (direct, method, conversion, 2step) (#695)
  • Support mapping from/to Java 14 records (preview feature) (#2014)
  • Add EnumTransformationStrategy and EnumNamingStrategy SPIs (#796, #1220, #1789, #1667 and PRs: #2089, #2100)

See release announcement for more information.


  • Add "verbose" processor option to print out details if required (#37) - Can be activated by using the compiler argument mapstruct.verbose=true
  • Qualifiers work dubiously in 2 step mappings (#1714) - See Behaviour changes
  • Skip java.lang.Object as intermediate result in 2 step mappings (#1698)
  • Add imports to @MapperConfig (#1435)
  • Annotation processor option for default injection strategy (#1792)
  • Inconsistency in support of containers (enum vs non enum type) (#1788) - Allow mapping between enum and non enum in the same way as mapping between primitive and objects
  • Strange error message when mapping with adder update method (#1719)
  • Support for conversion between java.time.LocalDateTime and javax.xml.datatype.XMLGregorianCalendar (#1791)
  • Do not allow using qualifiedBy and qualifiedByName with expression in Mapping (#1851) - This never worked, with this change we are adding a compile error if you try to use it.

Bug fixes

  • @BeanMapping(ignoreByDefault=true) in @MapperConfig not passed to mapping method (#1933)
  • unmappedSourcePolicy set to ERROR leads to a nested Bean issue (#1881)
  • <ANY_REMAING> and <ANY_UNMAPPED> not ignored when inverting Value mapping (#1936)
  • defaultExpression not being applied when source property not specified explicitly (#1966)
  • Error mapping processor from Set to Array of Object (#2001)
  • Wrong decorator class name used when Decorator class is nested inside mapper interface (#2021)
  • MapStruct should work properly on the module path (#2060)
  • "uses" entries ignored when used class is generated during annotation processing (#2056)
  • Problems with compiling in Eclipse with the Lombok javaagent (#1159)
  • NullPointer when accidentally using String source (#2077)


  • Split reference guide source into an adoc file per chapter (#991)
  • Documentation Update: jsr330/@DecoratedWith (#1773)
  • Add code-examples to Javadoc of org.mapstruct.* annotations (#166)
  • @InheritInverseConfiguration doesn't pickup ignore mapping (#1983)
  • Various typo fixes


  • Replace hickory:prism with the new MapStruct Tools Gem (#2011)
  • NullPointerException when building on OpenJDK 11 (#1675)
  • Move CI from Travis to GitHub Actions (#2019)
  • Update Checkstyle to 8.29 (#2016)
  • Switch to JUnit Jupiter and do not use Toolchains for the integration tests (#1308 and PR #2013)
  • Update tycho-compiler-jdt to 1.6.0 version (#1553)
  • Remove plexus-container-default dependency (#1857)

Codebase Enhancements

  • Refactor SourceReference (#1745)
  • Refactor: make sure that init of Mapping happens inside bean mapping scope (#1845)
  • Refactor the creation of ForgedMethod into a builder or static method creation (#1088)
  • model.source should reflect source only and not (intermediate) creation state (#1867)
  • Refactoring of BeanMapping and Source/TargetReferences (common base class) (PR #1903)
  • Simplify usage of inheritance of annotation fields in @MapperConfig, @Mapper, @BeanMapping, @Mapping, @IterableMapping and @MapMapping (#1998)
  • Various codebase changes by using more Java 8 features
  • Various codebase warning fixes (PRs: #1858, #1859, #1860, #1861, #1863, #1865, #1866, #1869, #1870, #1871, #1872)
  • Remove JaxbMapper from integration tests (#724) - Not needed anymore, since MapStruct can work without it. No changes for users
  • Remove not used method "asCollectionOrMap" from TypeFactory (#1883)
  • Remove unused methods from class SourceMethod (#1897)
  • Refactor class org.mapstruct.ap.internal.util.Filters (#1895)
  • Remove unused parameters from classes TargetTypeSelector, ValueMapping, MethodRetrievalProcessor (#1889)
  • Refactoring class Type (#1914)
  • Change return type MapperConfiguration.getBuilderPrism from Optional<BuilderPrism> to BuilderPrism (#1911)
  • Remove unused constants in JavaStreamConstants (#1944)
  • Fix minor warnings with collection in package model and util (#1948)
  • Simplify conditions in some classes (#1946)
  • Use Map.computeIfAbsent in NestedTargetPropertyMappingHolder (#1951)
  • Fix TODO items in integration tests (#1953)
  • Add test case with properties with underscore verifying that it is working as expected (#2018)
  • TargetReference refactorings (#2069)


Qualifiers should not qualify when no qualifier is found

Before when doing 2 step mappings MapStruct was forgetting the qualifiers and could select methods with other qualifiers. This is unexpected and has been changed so that qualifiers are always used.

See Issue #1714 and PR #1739 for more information.

Removed Deprecated Enum mapping

Before this release it was possible to use @Mapping for mapping enums. This is no longer possible and @ValueMapping should be used before. There was a warning before, so if you don't have that in your build then you don't need to do anything.


We'd like to thank all the contributors who worked on this release!