Skip to content
javahacks.dev
Spring Boot

Fix Could Not Resolve Placeholder in Spring Boot Value

Fix the Spring error about an unresolvable placeholder by checking the property name, the active profile, test resources and environment variable names.

6 min read
Summarize in AI
Flat illustration of a start button surrounded by Spring Boot starters, with the Spring Boot, Spring and Apache Maven logos.

The context fails to start and the cause is one line:

Text
java.lang.IllegalArgumentException: Could not resolve placeholder 'app.api-key' in value "${app.api-key}"

A field annotated with @Value("${app.api-key}") or a property file referencing ${app.api-key} has no value to substitute. Spring resolves those placeholders while building the bean, so the application refuses to start rather than run with a hole in its configuration. That is the behavior you want. This post covers the cases in the order they happen. Configuration sources are explained in Spring Boot from first project to production.

Cause 1: the property is not defined, or is spelled differently

java
@Value("${app.api-key}")
private String apiKey;
src/main/resources/application.propertiesproperties
app.apikey=secret

app.api-key and app.apikey are different keys in a @Value expression. Pick one spelling and match it. Prefer a typed @ConfigurationProperties class, which also validates and tolerates different forms in the file; see binding failures in application failed to start.

Cause 2: it is defined in a profile that is not active

A key in application-prod.properties does not exist when the active profile is dev. Check which profiles are active in the first log lines. Run with --spring.profiles.active=prod or set SPRING_PROFILES_ACTIVE.

Cause 3: a test resource hides the main file

If src/test/resources/application.properties exists, it takes the place of src/main/resources/application.properties for tests; the two do not merge. A test that fails with this error while the application runs is nearly always this. Put test overrides in application-test.properties, or inline them:

java
@SpringBootTest(properties = "app.api-key=test-key")
class BillingServiceTest { }

Cause 4: the environment variable has the wrong name

Relaxed binding turns APP_API_KEY into app.api-key. These do not work: API_KEY, APP.API.KEY in some shells, app-api-key. In a container, confirm the variable reached the process:

Shell
docker exec shop env | grep APP_

For Kubernetes, check the pod spec's env or envFrom and whether the Secret or ConfigMap exists in the namespace.

Cause 5: a placeholder inside a property value

Spring also resolves ${...} inside values:

properties
app.report-url=${app.base-url}/reports

If app.base-url is missing, the error names app.base-url and not app.report-url. Read the key in the message, not the line that failed first.

Defaults and when to use them

java
@Value("${app.page-size:20}")
private int pageSize;

The part after the colon is used when the key is absent. That is right for a tuning parameter with a safe default. It is wrong for a credential or a URL, where a silent empty value turns a startup failure into a runtime failure in front of users. For secrets, fail on purpose.

Know where Spring looked

The error names the key and says nothing about the places searched. The sources are checked in a fixed order, and the first match wins: command line arguments, SPRING_APPLICATION_JSON, Java system properties, operating system environment variables, then application-{profile} files, then application files, and finally @PropertySource and defaults. The full list is in configuration precedence. To see what the running application can resolve, ask the Environment in a test:

java
@SpringBootTest
class ConfigTest {

    @Autowired
    Environment env;

    @Test
    void apiKeyIsConfigured() {
        assertThat(env.getProperty("app.api-key")).isNotBlank();
    }
}

A test that fails with the same message as the application proves that the problem is in the configuration, and not in the way the application is launched.

Fail at startup with a clear message

A @Value placeholder fails the whole context with a stack trace, which an operator may not read quickly. Binding to a validated properties class reports each missing value by name:

java
@ConfigurationProperties(prefix = "app")
@Validated
record AppProperties(@NotBlank String apiKey, @Min(1) int timeoutSeconds) { }

Boot refuses to start with Binding to target ... failed and a list of the failed properties, app.api-key among them. The failure is still at startup, and the message tells the person who deploys what to fix. This is the form to use for anything required. See binding configuration.

Supplying a default, and when not to

A default after a colon removes the error, and it also removes the safety:

java
@Value("${app.page-size:20}")
int pageSize;

That is right for a tuning knob with a sensible value. It is wrong for a credential, a URL of another service or a feature switch with consequences. A missing database password with a default of an empty string produces an authentication error at the first query, which is later and further from the cause than the placeholder error. Use defaults for optional values only.

A resolver that ignores the problem

Spring has a switch to leave unresolved placeholders as literal text, ignoreUnresolvablePlaceholders on PropertySourcesPlaceholderConfigurer. It is meant for a second configurer in a layered context, and turning it on to silence this error means a request that later sends the string ${app.api-key} to a remote API as the key. Treat the error as correct and fix the property.

Quick diagnosis by environment

Where it failsWhat to check
Only in the IDEThe run configuration's active profiles and working directory
Only in testsA src/test/resources file that shadows the main one
Only in the containerEnvironment variable name, the mounted config path, the active profile
Only on CISecrets not exposed to the job, forks do not receive them
Only after a renameA stale value in a deployment manifest using the old key

The container row accounts for most production cases. The application starts on a laptop with a local file and in the cluster with none, and the placeholder error is the first sign that the manifest never supplied the value.

A configuration checklist for new properties

Most placeholder errors arrive with a new property. Adding one takes four steps, and skipping any is a future incident: add the key to the main configuration with a default or an empty marker and a comment, add it to the test configuration, add it to the deployment manifests of every environment, and add a line to the README. The properties class with validation then fails at startup in any environment that missed the third step.

A CI check can compare the keys referenced in code against the keys defined in the manifests, using a short script over application.yml and the deployment files. It finds the missing one on the pull request, when the author remembers the context.

Where this does not apply

A ${...} that must stay literal, for example in a message template or a Thymeleaf string, should not be a Spring placeholder; escape it or move it out of the property source. If a non-string property fails to convert instead, you have a binding error, not a placeholder error. The externalized configuration reference lists the order in which sources override each other, and [UnsatisfiedDependencyException](/library/unsatisfieddependencyexception-fix-spring) is the wrapper this error often arrives inside. The Spring Boot how-to guides documents the behavior in detail.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.