Spring.profiles.active Error in 3.5 – What Changed?

• ⚠️ Spring Boot 3.5 now enforces profile names to start and end with a letter or digit, breaking older configurations.
• 🧠 Profiles like _dev or prod- will now cause startup failures due to new, stricter rules.
• 🧰 Fixing profile names across CI/CD, Docker, and cloud environments is very important to get applications running again.
• ✅ Hyphens inside profile names are okay, but underscores and periods at the edges will cause errors.
• 📌 Adding profile checking in code or tests can help apps avoid wrong setups in the future.

Upgrading to Spring Boot 3.5 and then getting blocked by an error like "spring.profiles.active must start and end with a letter or digit"? You are not alone. This issue has surprised many developers. Their existing profile names worked fine in older versions. But with Spring Boot 3.5, a stricter rule for checking profile names arrived. This causes startup failures in places where configuration was not checked before. Let's look at what changed, why it matters, and how to fix it fast.

1. What is spring.profiles.active?

The spring.profiles.active property in Spring Boot is a key tool. It helps choose how the application acts in different environments. When a profile is active, Spring Boot loads specific settings for that profile. This includes beans, property files, and components. These settings fit the chosen environment.

Here are common ways to set it:

• In application.properties or application.yml files.
• As an environment variable. For example, in Docker images or hosted environments.
• Using JVM or command-line settings like --spring.profiles.active=dev.
• Through CI/CD tools or deployment scripts that work with environment setups.

For example:

spring.profiles.active=dev

This tells Spring Boot to load application-dev.properties instead of the default settings. This system helps make smooth changes between dev, test, staging, and prod. And it makes sure the application works right based on where it is running.

But this system needs profile names that are correct and recognized. This becomes very important in Spring Boot 3.5.

2. The Change in Spring Boot 3.5

In Spring Boot 3.5, rules for checking profile names are much stricter. Profiles that worked before are now not allowed.

🚫 The new rule:

Profile names must start and end with a letter (a-z, A-Z) or digit (0-9). Characters like hyphens are allowed inside names. But non-letters or non-numbers at the start or end are not allowed.

This makes the rules for using profiles clearer. It also helps setups stay consistent across projects.

Impact:

• An incorrect profile stops the application from starting.
• A profile name like _dev, which was okay before, now fails the check.
• Lists of multiple profiles (for example, dev,-qa) are also affected. If any name in the list is incorrect, the startup process stops.

The system now checks this new rule at the start. This helps prevent wrong profile names from causing problems. It also aims to make logs clearer.

3. What the Error Looks Like

Here is what developers see after updating:

Configuration:

spring.profiles.active=_dev

Output:

Caused by: java.lang.IllegalArgumentException: 
Invalid profile name '_dev': profile names must start and end with a letter or digit

Even if you list many profiles, just one incorrect name will cause the error:

spring:
  profiles:
    active: dev,qa_

You will get a similar error. It will say qa_ is wrong, even if dev is fine.

This check completely stops the app. There is no backup, no warning, and no default profiles will run. It just stops your application.

4. Why This Was Allowed Before (Before 3.5)

Before version 3.5, Spring Boot had very loose rules for profile names. The guides always suggested using simple names with letters and numbers. But nothing stopped you from using names like:

• _test
• qa-env
• .prod
• stage_

This loose approach happened because Spring Boot aimed for flexibility. This was helpful for scripting and CI/CD setups. Systems did not check name formats. And often, environments ended up with names that caused problems but still worked.

But this "freedom" caused issues:

• Hard to read.
• Names were not consistent across teams.
• Confusion when reading names with dots or dashes.
• Hidden startup problems when environments changed.

Spring Boot 3.5 fixes these past issues. It now clearly sets rules for what a valid profile name is.

5. Correct and Incorrect Profile Names in 3.5

A correct profile name will now follow a simple rule: It must start and end with a letter or number. This table shows what is allowed and what is not.

Tips:

• Hyphens are allowed inside names.
• Underscores at the start or end are not allowed.
• Do not use dots (.) and special characters unless truly necessary. And even then, keep them away from the ends of names.

6. The Fix: How to Solve the Error

🔧 Step-by-step fix:

1. Find ALL uses of spring.profiles.active in your code and infrastructure.
2. Change incorrect names to match the new rules.
3. Test environments well by starting the app with the updated profiles.
4. Check logs and running details to make sure the right profile is in use.

Example changes:

Check these areas that often have profile settings:

• 🧾 application*.properties or .yml files
• 📄 .env or .bashrc config scripts
• 🐳 Dockerfiles or docker-compose YAML
• 🚀 CI/CD pipeline YAML or scripts (GitHub Actions, Jenkins, GitLab, etc.)
• ☁️ Cloud provider UI (AWS Elastic Beanstalk, Azure App Settings, Heroku Config Vars)

7. Updating Dev and Prod Deployments – A Complete List

Changing profile names might affect more than just config files. Here is a full list for your environment to help you make the changes:

✅ Application Code & Build Tools

• Look through code for hardcoded spring.profiles.active strings.
• Check profile use in test annotations, for example, @ActiveProfiles.

🧪 Local Development

• Make sure .env and IDE run settings (e.g., IntelliJ or Eclipse) are updated.
• Check shell shortcuts or local deployment scripts.

🔧 Continuous Integration (CI)

• Review Jenkins job settings or shell scripts.
• Update GitHub Actions .yml with the correct profile in env or with block.
• Check environment variable injections in GitLab or Travis pipelines.

🐳 Docker & Kubernetes

• Change ENV spring.profiles.active lines in Dockerfiles.
• Update docker-compose.yml to use the new profile name.
• Check Kubernetes ConfigMaps, Secrets, and Helm chart values.

🌩️ Cloud Hosting

• AWS: Elastic Beanstalk environment variables.
• Azure: Web App settings.
• Heroku: Configuration variables using heroku config.

8. Why the Change? (From the Spring Boot Changelog)

Spring Boot is not just being strict. It is fixing old issues to make things easier to maintain.

Main reasons for the change:

• ✅ Stop apps from starting incorrectly because of wrong profile names.
• ✅ Make configuration reading simpler by removing confusion.
• ✅ Make rules clear for both systems and people checking deployments.

As stated in this Spring community discussion, this change makes things better for developers and helps with debugging. This is especially true when using many profiles.

9. Multi-profile Setups – Now Easier to Break

Lists of multiple profiles like this:

spring.profiles.active=dev,staging_,.uat,-canary

will cause the app to crash right away. This is because of the incorrect names (staging_, .uat, -canary).

You must fix all profile names in the list, not just the first or last one.

Fixed:

spring.profiles.active=dev,staging,uat,canary

Always check every profile use completely if you are sharing configurations across services or environments.

10. Checking Profiles in Code

For better automated checks and backup plans, you can add profile checking inside your app:

Java check:

for (String profile : environment.getActiveProfiles()) {
    if (!profile.matches("^[a-zA-Z0-9].*[a-zA-Z0-9]$")) {
        log.warn("Profile '{}' is incorrect. App startup may fail.", profile);
        // throw error or switch fallback
    }
}

Safer startup with a backup:

String fallbackProfile = "dev";
List<String> validProfiles = Stream.of(environment.getActiveProfiles())
    .filter(p -> p.matches("^[a-zA-Z0-9].*[a-zA-Z0-9]$"))
    .collect(Collectors.toList());

if (validProfiles.isEmpty()) {
    environment.setActiveProfiles(fallbackProfile); // use 'dev' as backup
}

This way helps when profile names come from changing sources. These can be feature flags, running settings, or outside secrets.

11. Testing

After you make fixes, make sure the correct profile is really active.

🧰 Log Check:

Start the app as usual and look at the log for:

The following profiles are active: staging

🧪 CLI Test:

./mvnw spring-boot:run -Dspring-boot.run.arguments=--spring.profiles.active=prod

✅ Integration JUnit:

@Test
@ActiveProfiles("prod")
void shouldLoadProdProfile() {
    assertTrue(Arrays.asList(environment.getActiveProfiles()).contains("prod"));
}

🔍 Actuator Check:

If you use Spring Boot Actuator, go to /env or /profiles to check:

{
  "activeProfiles": ["prod"]
}

12. Good Ways to Name Profiles From Now On

Make consistent naming a part of your team's process.

Do:

• ✅ Use only letters and numbers at the start and end.
• ✅ Put hyphens inside for easier reading: test-beta, staging-v2.
• ✅ Use lowercase names always: prod, not Prod.

Don’t:

• ❌ Add _, ., or - at the start of names.
• ❌ Rely on auto-setup with confusing profiles like prod. or qa-.

Tip:

Share a profile-naming.md file or an internal document. This should set your team's rules for naming profiles.

13. Final Thoughts: Watch Out for Upgrades

This issue shows that small updates can still change a lot in how things work. Always check release notes before big upgrades.

Team checklist:

• Lock dependencies using spring-boot-dependencies BOM.
• Add profile checking tests or checks when building the code.
• Write down supported profile names for your team.
• Update new hire guides and pull request templates with tips on profile naming.

Spring Boot 3.5 is not breaking things on purpose. It is helping developers use smarter, safer basic methods. These methods lead to better operations.

14. More Information

• Spring Boot Reference Docs on Profiles
• GitHub: Spring Boot 3.5 release notes
• StackOverflow Discussion

If this saved your team hours of debugging—or helped stop a bad deployment crash—share it with your dev team, post it in Slack.

Citations

StackOverflow. (2024). Spring Boot Upgrade to 3.5.0 – profile names must start and end with a letter or digit. StackExchange Network.