IllegalArgumentException: Source must not be null (BeanUtils.copyProperties)

Q: Add a null check before mapping

When to use: Use this if the object might legitimately be null.. Spring's BeanUtils does not handle null sources gracefully. You must guard the method call with a null check.

Q: Throw a custom exception if null

When to use: Use this if the object should never be null.. If the source object is null, it indicates a bug in your logic. Fail fast with a clear exception.

Q: Use Optional to handle nulls

When to use: Use this if you prefer functional programming style.. Wrap the object in Optional to safely handle nulls without explicit if-checks.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

2026-03-01 15:40:05.200 ERROR 8842 --- [nio-8080-exec-8] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: java.lang.IllegalArgumentException: Source must not be null] with root cause

java.lang.IllegalArgumentException: Source must not be null
	at org.springframework.util.Assert.notNull(Assert.java:201)
	at org.springframework.beans.BeanUtils.copyProperties(BeanUtils.java:738)

⚡ Quick Fix Works 80% of the time

Add a null check before calling BeanUtils.copyProperties.

if (source != null) {
    BeanUtils.copyProperties(source, target);
}

🧠 Why this Happens

Tap to expand the deep technical explanation

You called org.springframework.beans.BeanUtils.copyProperties(source, target), but the 'source' argument was null. Spring's utility class strictly prevents null sources to avoid silently overwriting target fields with nulls.

The HITEC City Parking Spot Analogy:

Imagine a copy machine asking you to place a document on the glass. If you press 'Copy' without putting any paper on the glass, the machine (BeanUtils) refuses to operate because the source is missing.

🔁 How to Reproduce Confirm this is your error

Call BeanUtils.copyProperties(source, target) with a null source object. It throws IllegalArgumentException: Source must not be null.

🛠️ Solutions (3 Ways to Fix)

Solution 1✓ Most common cause

Add a null check before mapping

👉 Use this if the object might legitimately be null.

Spring's BeanUtils does not handle null sources gracefully. You must guard the method call with a null check.

public UserDTO mapToDto(User user) {
    UserDTO dto = new UserDTO();
    if (user != null) {
        BeanUtils.copyProperties(user, dto);
    }
    return dto;
}

Solution 2

Throw a custom exception if null

👉 Use this if the object should never be null.

If the source object is null, it indicates a bug in your logic. Fail fast with a clear exception.

public UserDTO mapToDto(User user) {
    if (user == null) {
        throw new ResourceNotFoundException("User cannot be null");
    }
    UserDTO dto = new UserDTO();
    BeanUtils.copyProperties(user, dto);
    return dto;
}

Solution 3

Use Optional to handle nulls

👉 Use this if you prefer functional programming style.

Wrap the object in Optional to safely handle nulls without explicit if-checks.

public UserDTO mapToDto(User user) {
    UserDTO dto = new UserDTO();
    Optional.ofNullable(user).ifPresent(u -> BeanUtils.copyProperties(u, dto));
    return dto;
}

📋 Version Notes

Spring Boot 2.x

BeanUtils throws IllegalArgumentException for null sources.

Spring Boot 3.x

Identical behavior.

🛡️ How to Prevent This Next Time

Always validate inputs at the beginning of your mapping methods. Consider using MapStruct, which handles nulls automatically at compile time.