Introduction

Spring Boot 2 can bind application.properties values directly into Java 8 Duration fields, which makes timeout-style configuration much cleaner than manual parsing. The main ideas are simple: use a Duration property in your configuration class, write a supported duration string in properties, and optionally define a default unit when the property has no suffix.

Bind directly to java.time.Duration

A common setup uses @ConfigurationProperties:

1package com.example.demo.config;
2
3import java.time.Duration;
4import org.springframework.boot.context.properties.ConfigurationProperties;
5
6@ConfigurationProperties(prefix = "app")
7public class AppProperties {
8    private Duration timeout;
9
10    public Duration getTimeout() {
11        return timeout;
12    }
13
14    public void setTimeout(Duration timeout) {
15        this.timeout = timeout;
16    }
17}

Then in application.properties:

app.timeout=30s

Spring Boot converts the string into a Duration automatically.

Use supported units intentionally

Spring Boot supports suffixes such as:

• 'ns for nanoseconds'
• 'ms for milliseconds'
• 's for seconds'
• 'm for minutes'
• 'h for hours'
• 'd for days'

Examples:

app.connect-timeout=500ms
app.read-timeout=30s
app.cache-ttl=10m

This is usually easier to read than raw numeric millisecond values, especially when configuration files grow.

ISO-8601 format also works

You may also see ISO-8601 duration syntax such as:

app.timeout=PT30S

That is valid, but for ordinary application configuration many teams prefer the shorter Boot-style suffix form because it is easier to scan.

Use @DurationUnit when no suffix is present

If you want a bare number in properties and a default unit in code, annotate the field:

1package com.example.demo.config;
2
3import java.time.Duration;
4import java.time.temporal.ChronoUnit;
5import org.springframework.boot.context.properties.ConfigurationProperties;
6import org.springframework.boot.convert.DurationUnit;
7
8@ConfigurationProperties(prefix = "app")
9public class AppProperties {
10    @DurationUnit(ChronoUnit.SECONDS)
11    private Duration timeout;
12
13    public Duration getTimeout() {
14        return timeout;
15    }
16
17    public void setTimeout(Duration timeout) {
18        this.timeout = timeout;
19    }
20}

Now this property means seconds by default:

app.timeout=30

Without a suffix or @DurationUnit, the default interpretation may not match what you expect, so it is better to be explicit.

Use the bound duration in application code

Once bound, the value behaves like any ordinary Java Duration:

System.out.println(properties.getTimeout().toMillis());
System.out.println(properties.getTimeout().getSeconds());

That means you can keep your configuration readable while still getting strongly typed time values in the codebase.

Prefer explicit units in shared configurations

In teams, configuration files often outlive the code review context that created them. Explicit suffixes such as 30s or 500ms are usually easier for the next engineer to understand than a bare 30 paired with an annotation hidden in Java code. @DurationUnit is useful, but explicit unit strings in properties are often even clearer operationally.

Common Pitfalls

The most common mistake is forgetting the unit suffix and assuming Spring Boot will guess the intended unit the way you meant it.

Another common issue is mixing styles without documenting them, for example some properties using raw numbers and others using explicit suffixes.

People also bind the property as a String and parse it manually even though Spring Boot can already bind it directly to Duration.

Finally, if you want unitless values in properties, add @DurationUnit so the default is part of the code contract instead of tribal knowledge.

Summary

• Spring Boot 2 can bind property values directly to Java 8 Duration fields.
• Use clear suffixes such as ms, s, m, and h in application.properties.
• ISO-8601 durations also work, but short suffixes are often easier to read.
• Use @DurationUnit when properties omit the unit suffix.
• Prefer direct Duration binding over manual string parsing.