quarkusio/quarkus · error · IllegalArgumentException

Failed to convert value for property ${property} to String

Error message

Failed to convert value for property ${property} to String

What it means

doGetConfigValue retrieves config properties as String via ConfigProvider.getConfig().getOptionalValue(...). If the underlying config value exists but cannot be converted to String, an IllegalArgumentException from config lands here and is rethrown (or warned if not required) as 'Failed to convert value for property X to String'. It indicates a corrupt or non-convertible config source entry.

Source

Thrown at extensions/resteasy-reactive/rest-client/runtime/src/main/java/io/quarkus/rest/client/reactive/runtime/ConfigUtils.java:70

     * Obtains the value of the {@param propertyName} name, meaning that the name must NOT start with '${' or end with '}'
     */
    public static String doGetConfigValue(String configPropertyName, boolean required, String propertyName) {
        try {
            Optional<String> optionalValue = ConfigProvider.getConfig().getOptionalValue(propertyName, String.class);
            if (optionalValue.isEmpty()) {
                String message = String.format("Failed to find value for config property %s in application configuration. "
                        + "Please provide the value for the property, e.g. by adding %s=<desired-value> to your application.properties",
                        configPropertyName, propertyName);
                if (required) {
                    throw new IllegalArgumentException(message);
                }
                log.warn(message);
            }
            return optionalValue.orElse(null);
        } catch (IllegalArgumentException e) {
            String message = "Failed to convert value for property " + configPropertyName + " to String";
            if (required) {
                throw new IllegalArgumentException(message, e);
            } else {
                log.warn(message);
                return null;
            }
        }
    }

    private static String stripPrefixAndSuffix(String configProperty) {
        // by now we know that configProperty is of form ${...}
        return configProperty.substring(2, configProperty.length() - 1);
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Inspect the config source and make the property a plain scalar string value
2. Flatten the entry in YAML/TOML config (e.g. url: http://host:port instead of a nested block)
3. Remove duplicate definitions across config sources that conflict and choose a single valid source

Example fix

# before (application.yaml)
quarkus:
  rest-client:
    my-client:
      url: {host: localhost, port: 8080}
# after
quarkus:
  rest-client:
    my-client:
      url: http://localhost:8080

String v = ConfigProvider.getConfig().getOptionalValue("quarkus.rest-client.my-client.url", String.class).orElse(null);
if (v == null || !(v instanceof String) || v.isBlank()) {
    throw new IllegalStateException("Config value for my-client.url is missing or not a plain string");
}

try {
    // build/invoke client
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Failed to convert value for property")) {
        log.error("Check YAML/TOML config: the property must be a scalar string, not a nested mapping");
    }
    throw e;
}

When it happens

Trigger: A config source (e.g. YAML/TOML config file, KV store) supplies the rest-client property in a format MicroProfile Config cannot convert to String — often nested/structured values or null-typed entries in non-properties config sources.

Common situations: SmallRye YAML/TOML config files where the property ends up as a mapping/list instead of a scalar; quoting/encoding issues in the config file; custom ConfigSource returning an object type that fails conversion.

Related errors

• Unable to find provider for REST Client '${class}' with name
• Multiple providers found for REST Client '${class}'. Please
• Invalid expression: ${expression}
• Failed to find value for config property %s in application c
• The configuration ${clazz} must be an interface annotated wi

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/433335c2cbb1d6fe. Report an issue: GitHub.