Troubleshooting 'Mapstruct Qualified By Name Not Found' Error

Published on 2024.02.07

If you are working with Mapstruct and encounter the 'Qualified By Name Not Found' error, it can be quite frustrating. This error usually occurs when Mapstruct cannot find a qualified mapper implementation for a specific type. In this article, we will explore some possible causes and provide solutions to help you troubleshoot this error.

1. Incorrect Mapper Method Names

One possible reason for the 'Qualified By Name Not Found' error is that the mapper method names are not correct. Mapstruct relies on naming conventions to determine which method to use for mapping. Ensure that your mapper method names correspond to the source and target object types.

// Incorrect method name
@Mapper
public interface UserMapper {
    UserDto userToDto(User user);
}

// Correct method name
@Mapper
public interface UserMapper {
    UserDto mapUserToDto(User user);
}

2. Missing or Incomplete Mapper Definitions

Another common reason for this error is that you might have missed or incomplete mapper definitions. Mapstruct requires explicit mapping definitions for all the types used in the mapping process. Make sure that you have defined mappers for all the relevant types in your project.

// Missing mapper definition
@Mapper
public interface OrderMapper {
    OrderDto orderToDto(Order order);
}

// Correct mapper definition
@Mapper
public interface OrderMapper {
    OrderDto mapOrderToDto(Order order);
}

3. Incorrect Mapper Component Scanning

If you are using component scanning to register your mapper implementations, double-check if the package or classpath configurations are correct. Mapstruct relies on the correct component scanning to find the qualified mapper implementations.

// Incorrect component scanning
@ComponentScan(basePackages = "com.example.mappers")
public class AppConfig {
    // ...
}

// Correct component scanning
@ComponentScan(basePackages = "com.example.mapper")
public class AppConfig {
    // ...
}

4. Missing Mapstruct Annotation Processor

Mapstruct requires an annotation processor to generate the implementation classes for the mappers. Make sure that you have added the necessary dependencies and plugins to your build configuration to enable the annotation processing.

<!-- Incorrect Maven dependencies -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.4.2.Final</version>
</dependency>

<!-- Correct Maven dependencies -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.4.2.Final</version>
    <scope>provided</scope>
</dependency>

<!-- Incorrect Maven plugins -->
<plugin>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.4.2.Final</version>
    <scope>provided</scope>
</plugin>

<!-- Correct Maven plugins -->
<plugin>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.4.2.Final</version>
    <executions>
        <execution>
            <id>process</id>
            <goals>
                <goal>process</goal>
            </goals>
            <phase>generate-sources</phase>
        </execution>
    </executions>
</plugin>

Conclusion

The 'Qualified By Name Not Found' error in Mapstruct can be solved by ensuring correct mapper method names, complete mapper definitions, accurate component scanning, and proper configuration of the Mapstruct annotation processor. By following the troubleshooting steps provided in this article, you should be able to resolve this error and continue working with Mapstruct seamlessly.