Introduction

Spring Boot can bind environment variables to list properties, but the exact naming convention matters. In practice, the two most useful approaches are a single comma-separated variable or a set of indexed variables, both of which participate in Spring Boot’s relaxed binding system.

Bind a Comma-Separated Variable to a List

Suppose your application has a configuration property named app.allowed-hosts. With @ConfigurationProperties, Spring Boot can bind that property directly to a List<String>:

1import java.util.List;
2import org.springframework.boot.context.properties.ConfigurationProperties;
3
4@ConfigurationProperties(prefix = "app")
5public class AppProperties {
6    private List<String> allowedHosts;
7
8    public List<String> getAllowedHosts() {
9        return allowedHosts;
10    }
11
12    public void setAllowedHosts(List<String> allowedHosts) {
13        this.allowedHosts = allowedHosts;
14    }
15}

Then set one environment variable:

APP_ALLOWED_HOSTS=api.example.com,admin.example.com,internal.example.com

Spring Boot splits the value and binds it as a list. This is often the simplest solution for short string lists.

Use Indexed Variables When You Need More Control

If you prefer one variable per element, you can use indexed binding:

APP_ALLOWED_HOSTS_0=api.example.com
APP_ALLOWED_HOSTS_1=admin.example.com
APP_ALLOWED_HOSTS_2=internal.example.com

This style is helpful when deployment tooling manages each variable separately. The important mapping rule is that app.allowed-hosts becomes APP_ALLOWED_HOSTS.

Prefer @ConfigurationProperties Over Manual Splitting

Once the values are bound, you can inject and use them normally:

1import org.springframework.boot.CommandLineRunner;
2import org.springframework.stereotype.Component;
3
4@Component
5public class StartupLogger implements CommandLineRunner {
6    private final AppProperties appProperties;
7
8    public StartupLogger(AppProperties appProperties) {
9        this.appProperties = appProperties;
10    }
11
12    @Override
13    public void run(String... args) {
14        for (String host : appProperties.getAllowedHosts()) {
15            System.out.println(host);
16        }
17    }
18}

This is cleaner than reading one raw string with @Value and splitting it manually across the codebase.

Use SPRING_APPLICATION_JSON for Complex Structures

If the list becomes more complex, such as a list of nested objects, JSON can be easier to manage:

SPRING_APPLICATION_JSON='{"app":{"allowed-hosts":["api.example.com","admin.example.com"]}}'

That approach is especially useful in container environments where passing structured configuration as one variable is convenient.

Validate the Bound List Early

If the list is required, validate it at configuration-binding time instead of discovering bad values later during request handling:

1import jakarta.validation.constraints.NotEmpty;
2import org.springframework.validation.annotation.Validated;
3
4@Validated
5@ConfigurationProperties(prefix = "app")
6public class AppProperties {
7    @NotEmpty
8    private List<String> allowedHosts;
9
10    // getters and setters
11}

That lets the application fail fast when the environment variables are missing or malformed.

It also keeps configuration mistakes close to startup logs, which is much easier to debug than discovering them only after the first request path executes.

For operational settings such as allowed hosts, broker addresses, or bootstrap servers, that early validation is usually the difference between a quick deployment fix and a confusing runtime outage.

Common Pitfalls

The most common mistake is using the wrong environment variable name. Dots and hyphens from property names do not survive directly; Spring Boot expects uppercase names with underscores.

Another issue is assuming that every deployment platform passes commas and quotes exactly the same way. If values contain spaces or special characters, test how the shell or orchestrator actually passes them to the JVM.

People also mix indexed and comma-separated styles for the same property without understanding precedence, which can produce confusing overrides.

Finally, avoid scattering manual parsing logic across services when Spring Boot can bind the list for you once at startup.

Summary

• Spring Boot can bind lists from environment variables using comma-separated or indexed syntax.
• Translate property names such as app.allowed-hosts into APP_ALLOWED_HOSTS.
• Prefer @ConfigurationProperties for list binding instead of manual string splitting.
• Use SPRING_APPLICATION_JSON when the structure is more complex than a plain list of strings.
• Verify naming and quoting behavior in the real deployment environment.