When it comes to configuration refresh, the most frequent pitfall is “configuration changes not taking effect”. Follow this recommended troubleshooting sequence:
1. Verify the refresh pipeline
First confirm whether `/actuator/refresh` is actually invoked (check actuator logs or add an interceptor for tracing). A common mistake is failing to expose the refresh endpoint via `management.endpoints.web.exposure.include`, or misapplying `@RefreshScope`. Annotating `@Configuration` classes has no effect; the annotation should be placed on the specific injected beans.
Add logging with an `EnvironmentChangeEvent` listener to clearly see which keys are refreshed. If a key does not appear in this event, the configuration returned by Config Server matches the local cache, meaning the issue lies on the server side rather than the client.
2. Server-side cache and Git fetching
Config Server maintains local cache by default. An excessively large `spring.cloud.config.server.git.refresh-rate` results in stale values; set it to 0 during debugging.
In multi-instance deployments, only the Config Server instance receiving the request fetches updates from Git, while other instances keep stale cache. The standard approach is to broadcast `/bus/refresh` through Spring Cloud Bus (RabbitMQ / Kafka), instead of manually refreshing each instance one by one.
3. Common pitfalls for encryption and decryption
For symmetric encryption, `encrypt.key` must be explicitly configured and identical across all Config Server instances. Otherwise, ciphertext encrypted by one instance cannot be decrypted by another.
Ciphertext must follow the `{cipher}xxxx` format; the braces are mandatory. Wrap values containing special characters in YAML with single quotes.
For asymmetric encryption, be mindful of path changes after packaging when `encrypt.key-store.location` uses `classpath`. Using `file:` paths or mounted volumes is recommended.
Decryption failures throw exceptions and prevent application startup by default. Set `spring.cloud.config.server.encrypt.fail-on-error=false` to allow the service to start for troubleshooting.
4. Repository permissions
For HTTPS access, use username and password (or token). Avoid hardcoding credentials in configuration files; use environment variables or Vault instead.
A frequent SSH issue is missing `known_hosts`, which triggers `Host key verification failed`. Prepopulate `~/.ssh/known_hosts`, or set `spring.cloud.config.server.git.strict-host-key-checking=false` for test environments only.
Read-only permission is sufficient. Do not provide write credentials to Config Server.
5. An alternative approach
For high refresh frequency and large instance counts, instead of relying on Bus broadcasting, migrate to configuration centers with long-polling push such as Nacos or Apollo. Another option is adding a webhook in front of Config Server: trigger CI to call refresh endpoints on all instances upon Git push. This yields a more controllable pipeline and easier auditing.