mapstruct · arjun2075 · Aug 14, 2026
diff --git a/NEXT_RELEASE_CHANGELOG.md b/NEXT_RELEASE_CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Bugs
 
+* Propagate JSpecify `@Nullable` from the mapper method to the generated implementation's return type and parameters (#4076)
+
 ### Documentation
 
 ### Build

diff --git a/documentation/src/main/asciidoc/chapter-10-advanced-mapping-options.asciidoc b/documentation/src/main/asciidoc/chapter-10-advanced-mapping-options.asciidoc
@@ -334,6 +334,43 @@ This rule applies uniformly to bean, iterable, map, and stream mapping methods.
 
 When the return type of a mapping method is `@NonNull` (directly or via a `@NullMarked` scope), MapStruct forces `NullValueMappingStrategy.RETURN_DEFAULT` semantics. The generated method returns a default-constructed target (bean methods), an empty collection (`Iterable` / array mappings), an empty map (`Map` mappings), or `Stream.empty()` (stream mappings) rather than `null`, so the return contract is never violated. This rule applies regardless of the explicit `NullValueMappingStrategy` setting.
 
+==== Nullability in the generated implementation
+
+The generated implementation reproduces the `@Nullable` annotations of the mapping method it implements, so the implementation keeps the nullability contract of its interface and IDEs do not report the overriding method as missing nullness information:
+
+.Mapping method with JSpecify nullness annotations
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Mapper
+public interface CarMapper {
+
+    @Nullable
+    CarDto carToCarDto(Car car, @Nullable Options options);
+}
+----
+====
+
+The following implementation is generated:
+
+.Generated implementation keeping the nullability contract
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+public class CarMapperImpl implements CarMapper {
+
+    @Override
+    public @Nullable CarDto carToCarDto(Car car, @Nullable Options options) {
+        // ...
+    }
+}
+----
+====
+
+Only an explicit `@Nullable` is reproduced. A `@NonNull` nullability is deliberately not emitted: within a `@NullMarked` scope it is the implied default, so writing it out would add noise to every generated signature without changing the contract. Methods that MapStruct generates as internal helpers (rather than as an implementation of a mapper method) are not annotated, since they do not have to match an inherited signature.
+
 ==== Constructor parameter constraint
 
 If a property mapping would assign a potentially `null` source value to a `@NonNull` constructor parameter, MapStruct raises a *compilation error*. Neither inserting a null check (which would leave the variable at `null` and violate the contract) nor passing the value through is safe. Provide a `defaultValue` or `defaultExpression` on the `@Mapping` to satisfy the parameter when the source is absent.

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/AbstractMappingMethodBuilder.java b/processor/src/main/java/org/mapstruct/ap/internal/model/AbstractMappingMethodBuilder.java
@@ -8,12 +8,16 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import javax.lang.model.element.Element;
 
 import org.mapstruct.ap.internal.model.beanmapping.MappingReferences;
 import org.mapstruct.ap.internal.model.common.Assignment;
+import org.mapstruct.ap.internal.model.common.Parameter;
 import org.mapstruct.ap.internal.model.common.SourceRHS;
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.source.Method;
+import org.mapstruct.ap.internal.util.JSpecifyConstants;
+import org.mapstruct.ap.internal.util.NullabilityResolver;
 import org.mapstruct.ap.internal.util.Strings;
 
 /**
@@ -137,4 +141,47 @@ public List<Annotation> getMethodAnnotations() {
         return annotations;
     }
 
+    /**
+     * Propagates the JSpecify {@code @Nullable} annotations of the overridden mapper method onto the generated
+     * implementation's return type and source parameters.
+     * <p>
+     * Only explicit {@code @Nullable} annotations are reproduced. A {@code @NonNull} nullability is left out on
+     * purpose: within a {@code @NullMarked} scope it is the implied default, so emitting it would add noise to every
+     * generated signature without changing the contract.
+     * <p>
+     * Nothing is propagated for methods that do not override a mapper method (e.g. forged methods), since those are
+     * generated helpers that do not have to match an inherited signature.
+     *
+     * @param mappingMethod the mapping method to annotate
+     */
+    protected void propagateNullability(MappingMethod mappingMethod) {
+        if ( method instanceof ForgedMethod || !method.overridesMethod() ) {
+            return;
+        }
+
+        Type nullableType = null;
+
+        if ( isJSpecifyNullable( method.getExecutable() ) ) {
+            nullableType = getNullableAnnotationType();
+            mappingMethod.setNullableReturnTypeAnnotationType( nullableType );
+        }
+
+        for ( Parameter parameter : mappingMethod.getParameters() ) {
+            if ( parameter.getElement() != null && isJSpecifyNullable( parameter.getElement() ) ) {
+                if ( nullableType == null ) {
+                    nullableType = getNullableAnnotationType();
+                }
+                parameter.setNullableAnnotationType( nullableType );
+            }
+        }
+    }
+
+    private boolean isJSpecifyNullable(Element element) {
+        return ctx.getNullabilityInMapperScope( element ) == NullabilityResolver.Nullability.NULLABLE;
+    }
+
+    private Type getNullableAnnotationType() {
+        return ctx.getTypeFactory().getType( JSpecifyConstants.NULLABLE_FQN );
+    }
+
 }
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/BeanMappingMethod.java b/processor/src/main/java/org/mapstruct/ap/internal/model/BeanMappingMethod.java
@@ -523,7 +523,7 @@ else if ( !method.isUpdateMethod() ) {
                 mapNullToDefault = true;
             }
 
-            return new BeanMappingMethod(
+            BeanMappingMethod beanMappingMethod = new BeanMappingMethod(
                 method,
                 getMethodAnnotations(),
                 existingVariableNames,
@@ -544,6 +544,10 @@ else if ( !method.isUpdateMethod() ) {
                 subclassExhaustiveExceptionType,
                 sourceParametersReassignments
             );
+
+            propagateNullability( beanMappingMethod );
+
+            return beanMappingMethod;
         }
 
         private void keepMappingReferencesUsingTarget(List<LifecycleCallbackMethodReference> references, Type type) {

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/ContainerMappingMethodBuilder.java b/processor/src/main/java/org/mapstruct/ap/internal/model/ContainerMappingMethodBuilder.java
@@ -166,7 +166,7 @@ public final M build() {
         PresenceCheck sourceParameterPresenceCheck =
             PresenceCheckMethodResolver.getPresenceCheckForSourceParameter( method, null, sourceParam, ctx );
 
-        return instantiateMappingMethod(
+        M mappingMethod = instantiateMappingMethod(
             method,
             existingVariables,
             assignment,
@@ -178,6 +178,10 @@ public final M build() {
             selectionParameters,
             sourceParameterPresenceCheck
         );
+
+        propagateNullability( mappingMethod );
+
+        return mappingMethod;
     }
 
     private Assignment forge(SourceRHS sourceRHS, Type sourceType, Type targetType) {

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/MappingMethod.java b/processor/src/main/java/org/mapstruct/ap/internal/model/MappingMethod.java
@@ -41,6 +41,13 @@ public abstract class MappingMethod extends GeneratedTypeMethod {
     private final List<LifecycleCallbackMethodReference> beforeMappingReferencesWithoutMappingTarget;
     private final List<LifecycleCallbackMethodReference> afterMappingReferences;
 
+    /**
+     * The type of the JSpecify {@code @Nullable} annotation to emit in front of this method's return type, or
+     * {@code null} when nothing should be emitted. Only set for methods that override a mapper method, so that the
+     * generated implementation keeps the nullability contract of the interface it implements.
+     */
+    private Type nullableReturnTypeAnnotationType;
+
     /**
      * constructor to be overloaded when local variable names are required prior to calling this constructor. (e.g. for
      * property mappings). It is supposed to be initialized with at least the parameter names.
@@ -131,6 +138,19 @@ public Type getReturnType() {
         return returnType;
     }
 
+    /**
+     * @return the type of the JSpecify {@code @Nullable} annotation to emit in front of this method's return type,
+     *         or {@code null} when the return type's nullability must not be reproduced in the generated
+     *         implementation
+     */
+    public Type getNullableReturnTypeAnnotationType() {
+        return nullableReturnTypeAnnotationType;
+    }
+
+    public void setNullableReturnTypeAnnotationType(Type nullableReturnTypeAnnotationType) {
+        this.nullableReturnTypeAnnotationType = nullableReturnTypeAnnotationType;
+    }
+
     public Accessibility getAccessibility() {
         return accessibility;
     }
@@ -148,11 +168,15 @@ public Set<Type> getImportTypes() {
         Set<Type> types = new HashSet<>();
 
         for ( Parameter param : parameters ) {
-            types.addAll( param.getType().getImportTypes() );
+            types.addAll( param.getImportTypes() );
         }
 
         types.addAll( getReturnType().getImportTypes() );
 
+        if ( nullableReturnTypeAnnotationType != null ) {
+            types.add( nullableReturnTypeAnnotationType );
+        }
+
         for ( Type type : thrownTypes ) {
             types.addAll( type.getImportTypes() );
         }

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/common/Parameter.java b/processor/src/main/java/org/mapstruct/ap/internal/model/common/Parameter.java
@@ -38,6 +38,13 @@ public class Parameter extends ModelElement {
 
     private final boolean varArgs;
 
+    /**
+     * The type of the JSpecify {@code @Nullable} annotation to emit in front of this parameter's type, or
+     * {@code null} when nothing should be emitted. Only set for parameters of methods that override a mapper
+     * method, so that the generated implementation keeps the nullability contract of the interface it implements.
+     */
+    private Type nullableAnnotationType;
+
     private Parameter(Element element, Type type, boolean varArgs) {
         this.element = element;
         this.name = element.getSimpleName().toString();
@@ -113,9 +120,25 @@ private String format() {
             +  "%s " + name;
     }
 
+    /**
+     * @return the type of the JSpecify {@code @Nullable} annotation to emit in front of this parameter's type, or
+     *         {@code null} when the parameter's nullability must not be reproduced in the generated implementation
+     */
+    public Type getNullableAnnotationType() {
+        return nullableAnnotationType;
+    }
+
+    public void setNullableAnnotationType(Type nullableAnnotationType) {
+        this.nullableAnnotationType = nullableAnnotationType;
+    }
+
     @Override
     public Set<Type> getImportTypes() {
-        return Collections.asSet( type );
+        if ( nullableAnnotationType == null ) {
+            return Collections.asSet( type );
+        }
+
+        return Collections.asSet( type, nullableAnnotationType );
     }
 
     public boolean isTargetType() {
@@ -147,7 +170,7 @@ public boolean isSourceParameter() {
     }
 
     public Parameter withName(String name) {
-        return new Parameter(
+        Parameter parameter = new Parameter(
             name,
             this.name,
             type,
@@ -158,6 +181,8 @@ public Parameter withName(String name) {
             targetPropertyName,
             varArgs
         );
+        parameter.nullableAnnotationType = nullableAnnotationType;
+        return parameter;
     }
 
     @Override

diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/BeanMappingMethod.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/BeanMappingMethod.ftl
@@ -9,7 +9,7 @@
 <#list annotations as annotation>
     <#nt><@includeModel object=annotation/>
 </#list>
-<#lt>${accessibility.keyword} <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
+<#lt>${accessibility.keyword} <#if nullableReturnTypeAnnotationType??>@<@includeModel object=nullableReturnTypeAnnotationType/> </#if><@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#assign targetType = resultType />
     <#if !existingInstanceMapping>
         <#assign targetType = returnTypeToConstruct />

diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/IterableMappingMethod.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/IterableMappingMethod.ftl
@@ -10,7 +10,7 @@
 <#list annotations as annotation>
     <#nt><@includeModel object=annotation/>
 </#list>
-<#lt>${accessibility.keyword} <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
+<#lt>${accessibility.keyword} <#if nullableReturnTypeAnnotationType??>@<@includeModel object=nullableReturnTypeAnnotationType/> </#if><@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#list beforeMappingReferencesWithoutMappingTarget as callback>
     	<@includeModel object=callback targetBeanName=resultName targetType=resultType/>
     	<#if !callback_has_next>

diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/MapMappingMethod.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/MapMappingMethod.ftl
@@ -9,7 +9,7 @@
 <#list annotations as annotation>
     <#nt><@includeModel object=annotation/>
 </#list>
-<#lt>${accessibility.keyword} <@includeModel object=returnType /> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
+<#lt>${accessibility.keyword} <#if nullableReturnTypeAnnotationType??>@<@includeModel object=nullableReturnTypeAnnotationType/> </#if><@includeModel object=returnType /> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#list beforeMappingReferencesWithoutMappingTarget as callback>
     	<@includeModel object=callback targetBeanName=resultName targetType=resultType/>
     	<#if !callback_has_next>

diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/StreamMappingMethod.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/StreamMappingMethod.ftl
@@ -10,7 +10,7 @@
 <#list annotations as annotation>
     <#nt><@includeModel object=annotation/>
 </#list>
-<#lt>${accessibility.keyword} <@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
+<#lt>${accessibility.keyword} <#if nullableReturnTypeAnnotationType??>@<@includeModel object=nullableReturnTypeAnnotationType/> </#if><@includeModel object=returnType/> ${name}(<#list parameters as param><@includeModel object=param/><#if param_has_next>, </#if></#list>)<@throws/> {
     <#--TODO does it even make sense to do a callback if the result is a Stream, as they are immutable-->
     <#list beforeMappingReferencesWithoutMappingTarget as callback>
     	<@includeModel object=callback targetBeanName=resultName targetType=resultType/>

diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/common/Parameter.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/common/Parameter.ftl
@@ -6,4 +6,4 @@
 
 -->
 <#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.common.Parameter" -->
-<@includeModel object=type asVarArgs=varArgs/> ${name}
+<#if nullableAnnotationType??>@<@includeModel object=nullableAnnotationType/> </#if><@includeModel object=type asVarArgs=varArgs/> ${name}
diff --git a/processor/src/test/java/org/mapstruct/ap/test/bugs/_4076/Issue4076IterableMapper.java b/processor/src/test/java/org/mapstruct/ap/test/bugs/_4076/Issue4076IterableMapper.java
@@ -0,0 +1,51 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.test.bugs._4076;
+
+import java.util.List;
+
+import org.jspecify.annotations.Nullable;
+import org.mapstruct.Mapper;
+import org.mapstruct.MappingTarget;
+
+/**
+ * Covers the container mapping methods (iterable / map / stream) and update methods, which are built through
+ * {@code ContainerMappingMethodBuilder} rather than {@code BeanMappingMethod.Builder}.
+ */
+@Mapper
+public interface Issue4076IterableMapper {
+
+    @Nullable
+    List<String> mapList(@Nullable List<String> source);
+
+    void update(@Nullable Source source, @MappingTarget Target target);
+
+    class Source {
+
+        private String name;
+
+        public String getName() {
+            return name;
+        }
+
+        public void setName(String name) {
+            this.name = name;
+        }
+    }
+
+    class Target {
+
+        private String name;
+
+        public String getName() {
+            return name;
+        }
+
+        public void setName(String name) {
+            this.name = name;
+        }
+    }
+}