What causes "Could not resolve placeholder ' ' in string value " "" in pinpoint-apm/pinpoint?

Add the missing key to the properties file / environment so the resolver finds it

pinpoint-apm/pinpoint · error · IllegalArgumentException

Could not resolve placeholder '<placeholder>' in string valu

Error message

Could not resolve placeholder '<placeholder>' in string value "<strVal>"

What it means

parseStringValue() resolves each ${...} placeholder via the supplied resolver function. If no value can be resolved and ignoreUnresolvablePlaceholders is false (as in ValueAnnotationProcessor's instance and any helper built with ignore=false), it throws IllegalArgumentException naming both the placeholder and the original string being processed. When ignoreUnresolvablePlaceholders is true, the raw ${...} text is left in place instead.

Source

Thrown at commons-config/src/main/java/com/navercorp/pinpoint/common/config/util/spring/PropertyPlaceholderHelper.java:167

                        propVal = placeholderResolver.apply(actualPlaceholder);
                        if (propVal == null) {
                            propVal = defaultValue;
                        }
                    }
                }
                if (propVal != null) {
                    // Recursive invocation, parsing placeholders contained in the
                    // previously resolved placeholder value.
                    propVal = parseStringValue(propVal, placeholderResolver, visitedPlaceholders);
                    buf.replace(startIndex, endIndex + this.placeholderSuffix.length(), propVal);
                    startIndex = buf.indexOf(this.placeholderPrefix, startIndex + propVal.length());
                }
                else if (this.ignoreUnresolvablePlaceholders) {
                    // Proceed with unprocessed value.
                    startIndex = buf.indexOf(this.placeholderPrefix, endIndex + this.placeholderSuffix.length());
                }
                else {
                    throw new IllegalArgumentException("Could not resolve placeholder '" +
                            placeholder + "'" + " in string value \"" + strVal + "\"");
                }
                visitedPlaceholders.remove(originalPlaceholder);
            }
            else {
                startIndex = -1;
            }
        }

        return buf.toString();
    }

    private int findPlaceholderEndIndex(CharSequence buf, int startIndex) {
        int index = startIndex + this.placeholderPrefix.length();
        int withinNestedPlaceholder = 0;
        while (index < buf.length()) {
//            if (StringUtils.substringMatch(buf, index, this.placeholderSuffix)) {
            // copy spring StringUtils

View on GitHub (pinned to 744c3d3075)

Solutions

Add the missing key to the properties file / environment so the resolver finds it
Provide an inline default in the annotation, e.g. @Value("${some.key:defaultValue}")
Fix the placeholder key spelling in the @Value annotation to match the actual property name
Build the PropertyPlaceholderHelper with ignoreUnresolvablePlaceholders=true if raw text is acceptable

Example fix

// before
@Value("${collector.span.batch:size_missing}")
private int batchSize;
// after
@Value("${collector.span.batch:1024}")
private int batchSize;

Defensive patterns

Strategy: validation

Validate before calling

String key = "collector.span.batch";
if (!properties.containsKey(key)) {
    throw new IllegalStateException("Missing config key: " + key);
}

Try / catch

try {
    processor.process(configInstance, resolver);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Could not resolve placeholder")) {
        log.error("Missing property: {}", e.getMessage());
    }
}

Prevention

Always supply inline defaults: @Value("${key:default}") for optional settings
Keep environment property files synchronized — check new keys into every env file
Grep for ${...} keys in @Value annotations and diff them against the properties files at build time
Remember a missing key yields either this error (strict helper) or null/silent skip via getValue()'s catch of IllegalArgumentException

When it happens

Trigger: A @Value("${some.key}") annotation references a key absent from the resolver's properties map (with no ':' default), and the helper is strict; also nested resolution where the inner resolved key still cannot be found.

Common situations: Environment-specific property files missing a key that exists in other environments; renamed config keys after an upgrade while old @Value references remain; typo in the placeholder key inside the annotation; missing system environment variable that the resolver would map.

Related errors

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/4971db71f8280521. Report an issue: GitHub.