Introduction

This Spring Boot error means the template engine (usually Thymeleaf) cannot find a template file matching the name returned by your controller. The full error typically reads: Error resolving template [index], template might not exist or might not be accessible by any of the configured Template Resolvers. The root cause is almost always one of four things: the template file is in the wrong directory, the file extension does not match the resolver configuration, the controller returns a wrong name, or the template engine dependency is missing.

The Error in Context

1Whitelabel Error Page
2
3There was an unexpected error (type=Internal Server Error, status=500).
4Error resolving template [index], template might not exist or might not
5be accessible by any of the configured Template Resolvers

This happens when your controller returns a view name but Thymeleaf cannot find a matching file.

Fix 1: Put Templates in the Correct Directory

Thymeleaf's default location in Spring Boot is src/main/resources/templates/. The template file must be at:

1src/
2  main/
3    resources/
4      templates/
5        index.html       <-- Thymeleaf finds this
6      static/
7        style.css        <-- Static files go here, NOT templates

A controller returning "index" maps to templates/index.html. If your file is at templates/pages/index.html, the controller must return "pages/index".

1@Controller
2public class HomeController {
3
4    @GetMapping("/")
5    public String home() {
6        return "index";  // Maps to templates/index.html
7    }
8
9    @GetMapping("/about")
10    public String about() {
11        return "pages/about";  // Maps to templates/pages/about.html
12    }
13}

Fix 2: Check the File Extension

Thymeleaf expects .html files by default. If your template has a different extension, configure it:

# application.properties
spring.thymeleaf.suffix=.html

If you are using .htm or another extension:

spring.thymeleaf.suffix=.htm

Fix 3: Add the Thymeleaf Dependency

If you do not have the Thymeleaf starter in your project, Spring Boot has no template engine and cannot resolve any templates.

Maven:

1<dependency>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-thymeleaf</artifactId>
4</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'

Without this dependency, Spring Boot treats the return value as a response body (if @RestController) or fails to find a resolver (if @Controller).

Fix 4: Use @Controller, Not @RestController

1// WRONG — @RestController writes the string "index" directly to the response body
2@RestController
3public class HomeController {
4    @GetMapping("/")
5    public String home() {
6        return "index";  // Returns the literal string "index" as HTTP response
7    }
8}
9
10// CORRECT — @Controller treats the return value as a view name
11@Controller
12public class HomeController {
13    @GetMapping("/")
14    public String home() {
15        return "index";  // Resolves to templates/index.html
16    }
17}

@RestController = @Controller + @ResponseBody. It writes the return value directly to the response instead of resolving it as a template name.

Fix 5: Check the Prefix Configuration

If you have customized the template prefix, make sure it matches your directory structure:

1# Default (usually no need to change)
2spring.thymeleaf.prefix=classpath:/templates/
3
4# Custom prefix
5spring.thymeleaf.prefix=classpath:/views/
6# Now templates must be in src/main/resources/views/

Verify the prefix:

1@Autowired
2private ThymeleafProperties thymeleafProperties;
3
4@PostConstruct
5public void logConfig() {
6    System.out.println("Prefix: " + thymeleafProperties.getPrefix());
7    System.out.println("Suffix: " + thymeleafProperties.getSuffix());
8}

Fix 6: Check Case Sensitivity

Template names are case-sensitive on Linux but case-insensitive on macOS and Windows. A template named Index.html works on macOS but fails on a Linux deployment server when the controller returns "index".

1// Controller returns lowercase
2return "index";
3
4// File must be lowercase
5// templates/index.html  ✓
6// templates/Index.html  ✗ (fails on Linux)

Multi-Module and JAR Packaging Issues

When templates are in a separate module or library JAR, they must be on the classpath:

1my-library/
2  src/main/resources/
3    templates/
4      shared/header.html    <-- Must be in src/main/resources to end up in JAR

In a multi-module Maven project, ensure the module containing templates is a dependency:

1<dependency>
2    <groupId>com.example</groupId>
3    <artifactId>my-ui-templates</artifactId>
4</dependency>

If templates are excluded by the build (e.g., via maven-resources-plugin exclude filters), they will not be in the final artifact.

Debugging Template Resolution

Enable Thymeleaf debug logging to see exactly where it looks for templates:

logging.level.org.thymeleaf=DEBUG

This produces log output like:

[THYMELEAF] Trying to resolve template "index"
[THYMELEAF] Checking existence of resource: classpath:/templates/index.html

Using Multiple Template Engines

If you have both Thymeleaf and FreeMarker on the classpath, they may conflict. Each engine has its own resolver. Remove the one you are not using, or configure separate prefixes:

1# Thymeleaf templates in /templates/
2spring.thymeleaf.prefix=classpath:/templates/
3
4# FreeMarker templates in /freemarker/
5spring.freemarker.template-loader-path=classpath:/freemarker/

Common Pitfalls

• Templates in static/ instead of templates/: The static/ directory serves files directly (CSS, JS, images). Templates must be in templates/ for Thymeleaf to process them.
• Returning a path with leading slash: return "/index" may fail depending on the resolver configuration. Use return "index" (no leading slash).
• IDE not copying resources: In IntelliJ, sometimes resources are not copied to the build output. Run Build > Rebuild Project or check File > Project Structure > Modules > Sources to ensure src/main/resources is marked as a resources root.
• Spring Boot DevTools caching: Thymeleaf caches templates by default. During development, disable caching so changes are picked up: spring.thymeleaf.cache=false.
• WAR vs JAR packaging: Templates must be in src/main/resources/templates/ for JAR packaging. For WAR, they can also be in src/main/webapp/WEB-INF/templates/ depending on configuration.

Summary

• Templates must be in src/main/resources/templates/ with .html extension
• Use @Controller (not @RestController) to resolve view names
• Add spring-boot-starter-thymeleaf to your dependencies
• Return template names without leading slashes and matching the exact filename case
• Enable logging.level.org.thymeleaf=DEBUG to see where Thymeleaf looks for templates
• Disable template caching during development with spring.thymeleaf.cache=false