Frequently Asked Questions (FAQ)

How is MapStruct different from other bean mapping tools?

Unlike most other bean mapping tools, MapStruct doesn’t work at runtime but is a compile-time code generator.

Generating mapping code at build time has many advantages:

  • Early feedback about erroneous or incomplete mappings, in command line builds as well as within your IDE
  • Excellent performance, as no reflection or byte code generation at runtime is needed; the generated code contains plain method invocations, just as if the mapper was hand-written
  • No runtime dependencies, making MapStruct a great solution for Android applications
  • The generated code is easy to understand (and debug, if ever needed)
  • The optional Eclipse plug-in assists you when writing mappings, e.g. by auto-completion

Can I use MapStruct within Eclipse?


Check out the set-up instructions for Eclipse. There is also a work-in-progress Eclipse plug-in which facilitates the definition of mapper interfaces with auto-completion and some quick fixes.

Can I use MapStruct together with Project Lombok?

Yes, as of MapStruct 1.2.0.Beta1 and Lombok 1.16.14.

Project Lombok is an annotation processor that (amongst other things) adds getters and setters to the AST (abstract syntax tree) of compiled bean classes. AST modifications are not foreseen by Java annotation processing API, so quite some trickery was required within Lombok as well MapStruct to make both of them work together. Essentially, MapStruct will wait until Lombok has done all its amendments before generating mapper classes for Lombok-enhanced beans.

An example for using the two projects together can be found here.

If you are on an older version of MapStruct or Lombok, the solution is to put the JavaBeans to be amended by Lombok and the mapper interfaces to be processed by MapStruct into two separate modules of your project. Then Lombok will run in the compilation of the first module, causing the bean classes to be complete when MapStruct runs during the compilation of the second module.

Why does @Named not work?

Check out that you are actually using org.mapstruct.Named and not javax.inject.Named.

Why do I get this error: Could not retrieve @Mapper annotation during compilation?

This can happen if you are using mapstruct-jdk8 and some other dependency is using an older version of mapstruct. To solve the problem find the dependency that is using mapstruct and exclude it.

A known dependency that uses mapstruct and has this problem is springfox-swagger2.

For Maven you need to exclude it like:


For Gradle you need to exclude it like:

compile('io.springfox:springfox-swagger2:${swagger2.version}') {
    exclude group: 'org.mapstruct', module: 'mapstruct'