java.lang.NullPointerException: Cannot invoke "String.toLowerCase()" because the return value of "Customer.email()" is null
Java · updated 2026-11-13
Thrown when code calls a method or reads a field on a null reference. Since Java 14 the message says exactly which expression was null ("because the return value of Customer.email() is null"), and the first stack frame is the line. Older JVMs print a bare java.lang.NullPointerException.
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.toLowerCase()" because the return value of "Npe$Customer.email()" is null at Npe.receiptEmail(Npe.java:4) at Npe.main(Npe.java:5)
Quick fix
Read the "because" part of the message: it names the null expression. Find where that value comes from (a getter, a map lookup, a field a constructor didn't set, a JSON field) and decide: if it can be missing, handle it with a check or Optional; if it can't, validate it where the object is built with Objects.requireNonNull and a message.
- Read the message after "because": it names the null value (a method's return value, a field, a local or an array element).
- Open the first frame: that line dereferenced it.
- Trace the value back to where it is set: a constructor, a repository lookup, a deserialized request.
- Missing is normal: check for null or wrap it in Optional and handle the empty case.
- Missing is a bug: fail at construction with Objects.requireNonNull(value, "what is required"), so the error points at the cause.
// Can be missing: handle it
String email = Optional.ofNullable(customer.email())
.map(String::toLowerCase)
.orElse(null);
// Must exist: fail where the object is built, with a message
record Customer(String email) {
Customer {
Objects.requireNonNull(email, "customer.email is required");
}
}Paste this into Claude Code, Cursor or Codex in the project that throws it. The agent reads this guide in plain text and applies the fix that matches your stack.
Read https://runheed.com/errors/java-nullpointerexception.md and fix this error in this project.Why it happens
A lookup returned null
Map.get, a DAO method or a cache returns null for a missing key, and the caller chains a call onto it.
A field was never set
An object deserialized from JSON without the field, or built by a constructor or builder that skipped it, keeps null in that field.
Auto-unboxing a null
Assigning a null Integer or Boolean to an int or boolean (or comparing it with ==) throws NullPointerException on a line with no method call in sight.
Uninitialized collections or injected beans
A List field left null instead of empty, or a dependency used in a constructor before injection, throws on first use.
Other fixes
- Annotate with @Nullable/@NonNull and run NullAway or the Checker Framework so possible nulls fail the build.
- Return empty collections and Optional instead of null from your own methods.
- Validate request DTOs with Bean Validation (@NotNull) so a missing field is a 400, not a NullPointerException deep in the service.
Same error, other wording
- java.lang.NullPointerException: Cannot invoke "Object.toString()" because "value" is null
- java.lang.NullPointerException: Cannot read field "id" because "user" is null
- java.lang.NullPointerException: null
Let your coding agent catch the next one
Runheed records this error in production with the stack trace, the breadcrumbs before it and, when you set it, the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:
> Find the NullPointerException errors in production, read the "because" part of the latest one and its stack, work out why that value was null, and fix it where the value is loaded or built.
Setup for Java and Spring Boot, then have your agent fix and resolve it.
Related errors
- System.NullReferenceException: Object reference not set to an instance of an object.
- TypeError: Cannot read properties of undefined (reading 'x')
- AttributeError: 'NoneType' object has no attribute 'x'
More in Undefined, None and type errors
- panic: assignment to entry in nil mapGo
- TypeError: slugify(): Argument #1 ($title) must be of type string, null givenPHP
- System.InvalidOperationException: Sequence contains no elements.NET
- panic: runtime error: invalid memory address or nil pointer dereferenceGo
- NoMethodError: undefined method 'email' for nilRuby
- TypeError: Cannot destructure property 'id' of 'undefined' as it is undefined.Node.js
- TypeError: Cannot convert undefined or null to objectNode.js
- TypeError: items is not iterableNode.js
- TypeError: x is not a functionNode.js
- TypeError: Client is not a constructorNode.js
- ReferenceError: x is not definedNode.js
- ERR_INVALID_ARG_TYPE: The "path" argument must be of type string. Received undefinedNode.js
- TypeError: 'NoneType' object is not subscriptablePython
- TypeError: 'NoneType' object is not iterablePython
- KeyError: 'email'Python
- TypeError: unhashable type: 'list'Python
- AttributeError: 'dict' object has no attribute 'name'Python
- IndexError: list index out of rangePython
- TypeError: unsupported operand type(s) for +: 'int' and 'str'Python
- ValueError: invalid literal for int() with base 10: ''Python
- TypeError: __init__() got an unexpected keyword argument 'proxies'Python
- UnboundLocalError: cannot access local variable 'total' where it is not associated with a...Python
- RuntimeError: dictionary changed size during iterationPython
- ValueError: too many values to unpack (expected 2)Python
- TypeError: 'str' object is not callablePython
References: JEP 358: Helpful NullPointerExceptions, Java SE API: Objects.requireNonNull, Java SE API: Optional
Spotted a mistake? Email hello@greatwork.company. About Runheed.