Diagnosing Thymeleaf Template Caching Issues in Spring Boot

Recognizable Condition

You edit and save a Thymeleaf HTML template (e.g., src/main/resources/templates/index.html), refresh the browser, and the rendered page still shows the old markup. The change only appears after a full application restart.

Cause and Diagnostic Table

Possible Cause	How to Recognize It
Thymeleaf caching enabled (spring.thymeleaf.cache=true)	The TemplateEngine reuses parsed templates from memory; file system changes are ignored until the cache is cleared.
Missing Spring Boot DevTools	Without DevTools on the classpath, Spring Boot does not automatically disable caching or trigger a restart on file changes.
Custom TemplateResolver bean override	A manually defined SpringTemplateResolver bean with setCacheable(true) takes precedence over auto-configuration.
Incorrect resource path (Prefix/Suffix)	The application reads templates from a different directory than the one being edited, rendering a stale version from another location.

Ordered Diagnostic Checks

1. Verify the template location

   Confirm the edited file matches the configured template prefix and suffix. Run the following in your project root to locate all HTML templates:

   # Unix/macOS
   find src/main/resources -name "*.html" -type f
   
   # Windows PowerShell
   Get-ChildItem -Path src\main\resources -Recurse -Filter *.html | Select-Object -ExpandProperty FullName
   

   Ensure the file you are editing is the one being served by the application. Required permissions: Read access to source tree. Risk: None.

2. Check the active Thymeleaf cache setting

   If Spring Boot Actuator is enabled, query the environment endpoint to see the actual value of the cache property:

   curl -s http://localhost:8080/actuator/env | jq '.propertySources[] | select(.name | contains("applicationConfig")) | .properties | .["spring.thymeleaf.cache"]'
   

   If the endpoint is unavailable, check application.properties or profile-specific files (e.g., application-dev.properties). Required permissions: Network access to the actuator port. Risk: Exposing actuator endpoints in production without security.

3. Inspect the TemplateResolver bean

   Verify if a custom bean is overriding the default behavior. Use the actuator beans endpoint:

   curl -s http://localhost:8080/actuator/beans | jq '.[] | select(.bean | contains("templateResolver"))'
   

   Check the cacheable flag and the prefix/suffix properties. Required permissions: Actuator access. Risk: None.

4. Confirm DevTools presence

   Check your dependency tree to ensure spring-boot-devtools is present for local development:

   # Maven
   mvn dependency:tree | grep -i devtools
   
   # Gradle
   gradle dependencies | grep -i devtools
   

   If no output is returned, DevTools is not active. Required permissions: Read access to build files. Risk: None.

Fixes Tied to Findings

• If caching is enabled unintentionally: Set spring.thymeleaf.cache=false in your development profile (e.g., application-dev.properties). Alternatively, add spring-boot-devtools to your dependencies to automate this.
• If a custom TemplateResolver bean forces caching: Modify the bean to disable caching only in non-production profiles to maintain performance in production:

  @Bean
  @Profile("!prod")
  public SpringTemplateResolver templateResolver() {
      SpringTemplateResolver resolver = new SpringTemplateResolver();
      resolver.setPrefix("classpath:/templates/");
      resolver.setSuffix(".html");
      resolver.setCacheable(false); // Disable only in non-prod
      return resolver;
  }
  

• If the template path is wrong: Adjust spring.thymeleaf.prefix and spring.thymeleaf.suffix to point to the correct directory, or move your HTML files to match the existing configuration.

Verification and Limitations

To verify the fix, start the application with spring.thymeleaf.cache=false, change a visible string of text in a template, and refresh the browser. The update should appear without a restart.

Limitations:

• Do not disable caching in production; parsing templates on every request significantly increases CPU usage and response latency.
• Changes to application.properties require an application restart to take effect.
• Editing templates inside a packaged JAR file will not work; changes must be made to the source directory used by the resolver.

Escalation Criteria

If the internal Thymeleaf cache is disabled but changes still do not appear, investigate the following:

• Artifact Integrity: Verify the deployed JAR actually contains the update: jar -tf target/myapp.jar | grep templates/index.html.
• External Caching: Check for browser cache (perform a hard refresh via Ctrl+Shift+R), reverse-proxy caching (NGINX/Apache), or CDN layers.
• Resolver Priority: If multiple TemplateResolver beans exist, ensure the intended one is marked @Primary or has the correct @Order.