Lombok @Builder not initializing collections

I am using Lombok’s @Data and @Builder annotations like this:

@Data
@Builder(toBuilder = true)
class Movie {

    // Some other fields here.

    private final List<Actor> actors;

}

When I create a new Movie using the builder, without specifying any actors, I would expect Lombok to initialize my List to Collections.emptyList(). But this does not happen:

List<Actor> actors = Movie.builder().build().getActors();
System.out.println(actors); // Prints 'null'.

In the documentation for the @Builder annotation, it is stated at line 55 and 56 in the code-example for Vanilla Java (https://projectlombok.org/features/Builder.html) that I should look at the code example for @Singular (https://projectlombok.org/features/Singular-snippet.html). At line 112 in the Vanilla Java example here, it seems like the list should be initialized to the empty list.

I checked, and it does indeed happen if I annotate the list with @Singular:

@Data
@Builder(toBuilder = true)
class Movie {

    // Some other fields here.

    @Singular
    private final List<Actor> actors;

}

List<Actor> actors = Movie.builder().build().getActors();
System.out.println(actors); // Prints '[]'.

Is this a bug in Lombok, or is there something that I am doing wrong? According to the documentation, it seems like the list should be initialized to the empty list in both cases (because the @Builder doc refers to the @Singular doc).

Answer

Only when you use @Singular, you get an empty list. On the Builder documentation page it says:

…with the @Singular annotation, lombok will treat that builder node as a collection.

Without the @Singular, lombok treats it as any other object. So it will be null instead of an empty Collection.

Disclosure: I am a Lombok developer