Introduction

If a proxy setting is not working with Spring WebClient, the problem is usually that the proxy was configured in the wrong layer. WebClient commonly uses Reactor Netty underneath, so JVM-wide proxy settings or RestTemplate-era habits do not always affect it the way developers expect.

Configure the proxy on the underlying HttpClient

With Reactor Netty, the usual pattern is to configure the proxy on HttpClient and then plug that client into the WebClient connector:

1import io.netty.handler.proxy.ProxyHandler;
2import reactor.netty.http.client.HttpClient;
3import reactor.netty.transport.ProxyProvider;
4import org.springframework.http.client.reactive.ReactorClientHttpConnector;
5import org.springframework.web.reactive.function.client.WebClient;
6
7HttpClient httpClient = HttpClient.create()
8    .proxy(proxy -> proxy
9        .type(ProxyProvider.Proxy.HTTP)
10        .host("proxy.example.com")
11        .port(8080)
12    );
13
14WebClient webClient = WebClient.builder()
15    .clientConnector(new ReactorClientHttpConnector(httpClient))
16    .build();

If you configure something elsewhere and never attach it to the WebClient, the requests will bypass the proxy.

System properties are not always enough

Developers often expect Java system properties such as http.proxyHost and http.proxyPort to just work automatically. That can help some client stacks, but Reactor Netty is explicit enough that many production setups configure the proxy directly rather than relying on JVM-global defaults.

That is one reason proxy behavior may seem inconsistent when switching from older HTTP clients to WebClient.

HTTPS still usually goes through the HTTP proxy

Another source of confusion is HTTPS. In most enterprise environments, an HTTPS destination still uses an HTTP proxy tunnel via CONNECT. So the proxy type is often still HTTP even when the target URL is HTTPS.

If you misclassify the proxy or assume the scheme of the destination should match the proxy type, requests may fail in ways that look unrelated.

Proxy authentication needs explicit configuration too

If the proxy requires credentials, configure them in the proxy provider:

1HttpClient httpClient = HttpClient.create()
2    .proxy(proxy -> proxy
3        .type(ProxyProvider.Proxy.HTTP)
4        .host("proxy.example.com")
5        .port(8080)
6        .username("user")
7        .password(p -> "secret")
8    );

A missing username or password can make it look like the proxy is ignored when the real issue is authentication failure.

Verify with logs and a known target

Do not debug proxy configuration against a vague failing service first. Use a simple known endpoint and enable client-side logging or network tracing. That helps answer:

• is the request leaving through the proxy
• is the proxy rejecting it
• is DNS resolution failing before proxy use

Without that separation, proxy bugs often get confused with SSL or remote-service bugs.

Watch out for environment mismatches

A proxy that works locally may fail in containers, CI, or Kubernetes because the network route, DNS, or environment variables differ. WebClient configuration that is correct in code can still fail if the runtime environment cannot actually reach the proxy host.

That is why proxy debugging is partly an application configuration task and partly a network-path verification task.

Common Pitfalls

• Setting proxy properties globally and assuming WebClient will automatically honor them.
• Configuring a proxy on HttpClient but not wiring that client into WebClient.
• Forgetting proxy authentication when the corporate proxy requires it.
• Misunderstanding HTTPS proxying and choosing the wrong proxy type.
• Debugging only the application code without verifying network reachability to the proxy host.

Summary

• Spring WebClient proxy behavior usually depends on the underlying Reactor Netty HttpClient configuration.
• The most reliable fix is to configure the proxy explicitly on HttpClient and attach it to WebClient.
• HTTPS targets often still use an HTTP proxy via tunneling.
• Proxy authentication must be configured explicitly when required.
• Separate application misconfiguration from network-path and environment issues when troubleshooting.