alibaba/nacos · error · IllegalArgumentException

Cannot convert String [{property}] to Long

Error message

Cannot convert String [{property}] to Long

What it means

Thrown by LongConverter.convert() as an IllegalArgumentException when Long.valueOf(property) fails. An empty or null string returns null (no error). This converter is used internally by NacosClientProperties to coerce string property values to Long. The message includes the offending value in brackets.

Source

Thrown at client-basic/src/main/java/com/alibaba/nacos/client/env/convert/LongConverter.java:31

 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.alibaba.nacos.client.env.convert;

import com.alibaba.nacos.common.utils.StringUtils;

class LongConverter extends AbstractPropertyConverter<Long> {
    
    @Override
    Long convert(String property) {
        if (StringUtils.isEmpty(property)) {
            return null;
        }
        try {
            return Long.valueOf(property);
        } catch (Exception e) {
            throw new IllegalArgumentException("Cannot convert String [" + property + "] to Long");
        }
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Check the property value in the exception message and ensure it is a valid 64-bit signed integer.
2. Remove thousands separators, units, and whitespace.
3. If the value represents a timestamp or duration, convert it to epoch millis or seconds before setting the property.

Example fix

// before
props.setProperty("some.long.property", "1,700,000,000,000");

// after
props.setProperty("some.long.property", "1700000000000");

String raw = properties.getProperty("some.long.property");
if (raw != null && !raw.isEmpty()) {
    try {
        Long.parseLong(raw.trim());
    } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Property must be a valid long: " + raw, e);
    }
}

try {
    Long value = Long.valueOf(raw);
} catch (NumberFormatException e) {
    value = defaultValue;
}

When it happens

Trigger: A Nacos property expected to be a long integer contains a non-numeric string (e.g. 'abc', '1.5', '1,000,000', '99999999999999999999' overflow).

Common situations: Large numeric IDs or timestamps formatted with separators; scientific notation; overflow beyond Long.MAX_VALUE; locale-specific comma separators.

Related errors

• Invalid boolean value '{}'
• Cannot convert String [{}] to Integer
• [http-client] invalid connect timeout:{}
• Illegal url path expression
• converter not found, can't convert from String to {}

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/bbd580a19ba18d87. Report an issue: GitHub.