java.lang.IllegalStateException: Resource 'messages.properties' not found

Q: Create the default messages.properties file

When to use: Use this if you are using i18n but haven't created the file yet.. Create the file exactly where Spring expects it.

Q: Fix the spring.messages.basename property

When to use: Use this if your file has a different name.. If your file is named `custom.properties`, you must tell Spring Boot to look for `custom` instead of `messages`.

Q: Exclude MessageSourceAutoConfiguration

When to use: Use this if you do not need internationalization at all.. Tell Spring Boot to stop looking for message files entirely.

Q: Check target folder compilation

When to use: Use this if the file exists in `src/main/resources` but Spring still can't find it.. Maven might be excluding it during the build. Check your `target/classes` folder. If it's missing, clean and rebuild.

Q: Provide a custom MessageSource bean

When to use: Use this if you need fine-grained control over file loading.. Manually instantiate the `ResourceBundleMessageSource` and set the basenames programmatically.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

2026-02-20 20:15:22.410 ERROR 8842 --- [           main] o.s.boot.SpringApplication               : Application run failed

java.lang.IllegalStateException: Resource 'messages.properties' not found
	at org.springframework.boot.context.config.MessageSourceAutoConfiguration.getBaselineMessageSource(MessageSourceAutoConfiguration.java:108)

⚡ Quick Fix Works 80% of the time

Create a messages.properties file in src/main/resources/.

# src/main/resources/messages.properties
user.email.invalid=Invalid email format

🧠 Why this Happens

Tap to expand the deep technical explanation

Spring Boot auto-configures a `MessageSource` and expects a default file named `messages.properties` to exist in `src/main/resources/`. If the file is missing, or if you specified a `spring.messages.basename` that doesn't exist on the classpath, Spring throws this `IllegalStateException` to prevent the app from starting without its translations.

The HITEC City Parking Spot Analogy:

It's like a textbook printer trying to bind a book, but the chapter files were never uploaded to the server. The printer halts the entire job because the core content is missing.

🔁 How to Reproduce Confirm this is your error

Create a Spring Boot app. Add `spring.messages.basename=translations` to application.properties. Do NOT create a `translations.properties` file. Run the app.

🛠️ Solutions (5 Ways to Fix)

Solution 1✓ Most common cause

Create the default messages.properties file

👉 Use this if you are using i18n but haven't created the file yet.

Create the file exactly where Spring expects it.

# File: src/main/resources/messages.properties
# Content:
greeting=Hello from DevInHyderabad!

Solution 2

Fix the spring.messages.basename property

👉 Use this if your file has a different name.

If your file is named `custom.properties`, you must tell Spring Boot to look for `custom` instead of `messages`.

# application.properties
spring.messages.basename=custom

Solution 3

Exclude MessageSourceAutoConfiguration

👉 Use this if you do not need internationalization at all.

Tell Spring Boot to stop looking for message files entirely.

@SpringBootApplication(exclude = {MessageSourceAutoConfiguration.class})
public class Application { ... }

Solution 4

Check target folder compilation

👉 Use this if the file exists in `src/main/resources` but Spring still can't find it.

Maven might be excluding it during the build. Check your `target/classes` folder. If it's missing, clean and rebuild.

mvn clean install

Solution 5

Provide a custom MessageSource bean

👉 Use this if you need fine-grained control over file loading.

Manually instantiate the `ResourceBundleMessageSource` and set the basenames programmatically.

@Bean
public MessageSource messageSource() {
    ResourceBundleMessageSource source = new ResourceBundleMessageSource();
    source.setBasenames("messages", "errors");
    return source;
}

📋 Version Notes

Spring Boot 2.x

Standard MessageSource auto-configuration.

Spring Boot 3.x

Stricter startup validation. Fails immediately if the configured basename is missing.

🛡️ How to Prevent This Next Time

When setting up i18n, create the `messages.properties` file in `src/main/resources/` before adding the `spring.messages.basename` property to your configuration.