Spring Boot 3.5.8: Fixing Null HTTP Headers In RestTemplate

Hey guys! Ever been in that frustrating spot where you're upgrading your Spring Boot application, everything seems fine, and then boom—a NullPointerException pops up in the most unexpected place, especially when dealing with RestTemplate and HTTP headers? If you've recently made the leap to Spring Boot 3.5.8 (or a similar newer version) from an older one like 3.2.5, and you're suddenly seeing errors related to null header values, then you've landed in the right place. This article is all about demystifying that sudden change in behavior and, more importantly, giving you some solid ways to fix it. We're going to dive deep into why this is happening, what's changed under the hood, and how you can gracefully handle null values in your HttpHeaders without your application crashing.

Uh Oh, NullPointerException! What Happened to Our RestTemplate?

So, let's talk about the dreaded NullPointerException that's been messing with your RestTemplate calls. You're probably scratching your head because, like many, you had a piece of code that was working perfectly fine in Spring Boot 3.2.5. Imagine this common scenario: you're constructing HttpHeaders, adding a ContentType, and then, sometimes, you need to add a custom header, say rid, which might occasionally have a null value. In your older Spring Boot setup, headers.add("rid", SOME_VALUE_THAT_CAN_BE_NULL) would just work. No fuss, no muss. The system would silently handle that null value, perhaps by simply omitting the header or converting it to an empty string, and your API call would go through. Fast forward to your shiny new Spring Boot 3.5.8 environment, and suddenly, the exact same line of code is blowing up your application with a NullPointerException.

This isn't just an annoying bug; it's a regression in behavior that can stop your migration dead in its tracks. The stack trace you're seeing likely points straight to java.lang.NullPointerException: value and then dives into something like jdk.internal.net.http.HttpRequestBuilderImpl.checkNameAndValue or jdk.internal.net.http.HttpRequestBuilderImpl.header. This is a huge clue, guys! It tells us that the problem isn't necessarily with Spring's HttpHeaders itself, but rather with the underlying HTTP client that Spring is now using to actually send your request. Specifically, the error indicates that the Java Development Kit's (JDK) internal HTTP client, which is part of the java.net.http package introduced in Java 11, is being invoked. This client has a much stricter approach to validating header names and values. When it encounters a null value where it expects a non-null string for a header, it doesn't just ignore it or convert it; it throws an NPE because it adheres strictly to the HTTP specification which typically doesn't allow null header values. The frustration here stems from the lack of clear documentation highlighting this change during a minor version upgrade, making it a surprise for many developers. Understanding this shift is the first step to truly fixing the problem, rather than just patching it. We need to acknowledge that the old implicit behavior, while convenient, might have been a bit too lenient, and the new behavior, while stricter, is technically more compliant with how HTTP headers should be handled. So, let's get ready to adjust our code to meet these new, more stringent requirements, ensuring our applications are robust and compliant.

Diving Deep: The Shift from Apache HttpClient to JdkClientHttpRequest

Alright, let's unravel the mystery behind why your perfectly good code suddenly decided to go on strike. The core reason for this NullPointerException lies in a fundamental change in how RestTemplate handles its actual HTTP requests under the hood, particularly in newer Spring Boot versions. In earlier versions of Spring Boot, your RestTemplate might have been implicitly using SimpleClientHttpRequestFactory, which internally often relied on HttpURLConnection, or more commonly, if you had Apache HttpClient on your classpath (which is a very popular choice for many Spring applications), it would leverage HttpComponentsClientHttpRequestFactory. These older implementations, or rather their internal handling of headers, were more forgiving. For instance, the SimpleClientHttpRequest that many of us relied on had a line like String actualHeaderValue = headerValue != null ? headerValue : ""; within its addHeaders method. See that? It explicitly checked if a header value was null and, if it was, it would default it to an empty string. This was a safety net that many developers unknowingly benefited from.

However, with Java 11 came the shiny, new, built-in java.net.http.HttpClient API, a modern and often more performant HTTP client designed to replace HttpURLConnection and reduce external dependencies. Newer versions of Spring Framework and Spring Boot have embraced this new JDK HTTP client, and consequently, RestTemplate now defaults to using JdkClientHttpRequestFactory and its corresponding JdkClientHttpRequest when the Java version supports it. This is where our NullPointerException rears its ugly head. The JdkClientHttpRequest internally delegates to the java.net.http.HttpRequest.Builder to construct the actual HTTP request. And here's the kicker: this builder is much stricter. The method HttpRequestBuilderImpl.header() (which JdkClientHttpRequest eventually calls) includes a crucial check: Objects.requireNonNull(value). This requireNonNull method does exactly what its name suggests: if the value you pass to it is null, it immediately throws a NullPointerException with the message