Diagnosing Thymeleaf Template Resolution Failures in Spring Boot

Problem Statement

When a Spring Boot application returns org.thymeleaf.exceptions.TemplateInputException with a message such as Error resolving template ‘myTemplate’, template might not exist or might not be accessible, the underlying issue is almost always a mismatch between the view name the controller returns and the actual template file on the classpath. The error can also surface when the template contains an invalid expression that references a missing model attribute.

Typical Symptom

The stack trace ends with:

org.thymeleaf.exceptions.TemplateInputException: Error resolving template ‘myTemplate’, template might not exist or might not be accessible
    at org.thymeleaf.TemplateEngine.process(TemplateEngine.java:…)
    …

In a development environment the error often disappears after a clean rebuild, but reappears when running the executable JAR or deploying to a production server.

Diagnostic Table

Condition	Likely Cause
TemplateNotFoundException	File missing from classpath or wrong location
TemplateInputException (processing)	Invalid SpringEL expression or null‑safe navigation missing
Cache‑related error	spring.thymeleaf.cache=true with stale template in JAR

Ordered Checks

1. Verify the template file exists in the built artifact.
   • Run jar tf target/yourapp.jar | grep templates/ to list all templates.
   • Confirm the file name and case exactly match the view name returned by the controller.
2. Check the view name in the controller.
   • Do not prefix the returned string with a slash (e.g., return /myTemplate; should be myTemplate).
   • Ensure the case matches the file on disk; Windows is case‑insensitive but Linux is not.
3. Enable DEBUG logging for Thymeleaf.
   • Add to application.yml:

     logging.level.org.thymeleaf=DEBUG

   • Run the application and look for lines like Resolving template ‘myTemplate’ with resolver ‘SpringResourceTemplateResolver’ to see which resolver is used and why it fails.
4. Test with the template cache disabled.
   • Add to application.yml:

     spring.thymeleaf.cache=false

   • Re‑run the application. If the error disappears, the template was missing at build time but present at runtime.
5. Isolate the failing expression.
   • Create a minimal template containing only the suspect expression, e.g., <p th:text="${user.address.city}"></p>.
   • Return this template from a controller and verify if the exception still occurs. If it does, the issue is an invalid expression rather than a resolver problem.

Common Fixes

• Move templates to src/main/resources/templates/ so they are on the classpath.
• Remove leading slashes and correct case in the controller’s return value.
• Use safe navigation in expressions: ${user?.address?.city} or guard with th:if.
• Only set spring.thymeleaf.cache=false in application-dev.yml or via @Profile("dev") to avoid performance hits in production.
• If using a custom ITemplateResolver, verify its prefix and suffix match the actual file layout.

Escalation Criteria

• When a custom ITemplateResolver is in use and the above checks do not resolve the issue.
• When the error only surfaces in a native image built with GraalVM.
• When running under a non‑standard servlet container (e.g., Jetty) that may alter classpath resolution.

Practical Verification Steps

1. Build the application:

   ./mvnw clean package

2. Inspect the JAR:

   jar tf target/yourapp.jar | grep templates/myTemplate.html

3. Run the JAR with debug logging:

   java -jar target/yourapp.jar --logging.level.org.thymeleaf=DEBUG

4. Check the console for resolver output. A line like TemplateResolver: SpringResourceTemplateResolver, template: myTemplate indicates the resolver is being invoked.
5. If the resolver reports Template not found, confirm the file path inside the JAR matches the expected templates/ directory.

Limitations

These steps assume Thymeleaf 3.x and Spring Boot 3.x. Earlier versions may use different resolver names or property keys. Always check the org.thymeleaf package version in your pom.xml and adapt the property names accordingly.

Conclusion

Template resolution failures are usually a matter of file location, naming, or expression syntax. By following the ordered checks above, you can quickly pinpoint whether the problem lies in the resolver chain or in the template content itself. Once identified, the fixes are straightforward and can be verified with minimal effort.