Spring Cloud refresh: changed properties do not rebuild every dependency

Inspect the object graph

A service may refresh a retry interval while an HTTP client created at startup retains its previous timeout. A @RefreshScope proxy can rebuild a target on its next use, but putting the annotation on a configuration class does not automatically make every bean returned by that class refresh scoped. Constructor-bound records have additional limits. A concurrent reader can observe a partially rebound mutable properties object unless the refresh boundary protects it.

Restrict the control plane

The refresh actuator endpoint changes live behavior and should be exposed only to an authenticated operator path. A deployment rollout is often simpler for connection pools and other stateful clients. Spring AOT/native processing does not support context refresh, so native deployments should treat such changes as new image releases.

Test old and new work

Start one request before refresh and another afterward. Verify which timeout each sees, what happens to open connections, and whether a removed property actually disappears. Do not call refresh complete just because Environment returns a new string. This is a design sketch; the specific bean graph requires an application test.

Implementation sketch

@Bean
@RefreshScope
ParcelGateway parcelGateway(ParcelGatewaySettings settings) {
    return new ParcelGateway(settings.readTimeout());
}

Cost and verification

Refresh can allocate a new client while old requests still use the former one. Track connection ownership and cleanup; an application restart is often easier to reason about for stateful dependencies.

Common Mistakes

• Do not assume every singleton is rebuilt after /actuator/refresh.
• Do not expose refresh as an unauthenticated public endpoint.
• Do not promise live refresh in an AOT/native image deployment.

Read next

Spring Cloud Config label: pin a release to the configuration it was tested with, Spring AOT: profile and conditional beans become build-time decisions, Spring exercise: trace selected config and staged Boot migrations, Spring HTTP client timeouts: bound the call inside the request deadline.

Related boundary

Spring Cloud Kubernetes reload: decide which changes need a restart