How @Nullable Prevents Spring Bean Injection Failures

Environment: Spring 5.3.23

1. Introduction

In the Spring framework, dependency injection decouples components, but injecting a non‑existent bean causes startup errors. This article introduces best practices to avoid such errors, focusing on using the @Nullable annotation as an alternative to other techniques.

2. Reproducing the Error

static class PersonDAO {
}
@Component
static class PersonService {
  @Autowired
  private PersonDAO dao ;
  public void find(Integer id) {
    System.out.println("id = " + id.toString()) ;
  }
}

The PersonDAO class is not registered as a bean, yet PersonService autowires it, causing a startup failure.

Caused by: org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type 'com.pack.main.autowired_resource.ResourceInjectAndNullableMain2$PersonDAO' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {@org.springframework.beans.factory.annotation.Autowired(required=true)}
  at org.springframework.beans.factory.support.DefaultListableBeanFactory.raiseNoMatchingBeanFound(DefaultListableBeanFactory.java:1801)

The container expects a PersonDAO bean that does not exist.

3. @Nullable Annotation

Using @Nullable on the field prevents the error.

@Nullable
@Autowired
private PersonDAO dao ;

This works with Spring’s own org.springframework.lang.Nullable annotation.

@javax.annotation.Nullable
@Autowired
private PersonDAO dao ;

Custom @Nullable annotation also works:

@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
static @interface Nullable {
}

Applying the custom annotation also avoids startup errors.

4. Underlying Mechanism

During injection Spring wraps the target in a DependencyDescriptor. Its isRequired() method checks the required flag and whether the field has an @Nullable annotation (or is Optional, Kotlin nullable, etc.). If @Nullable is present, the descriptor is not required, so missing beans are tolerated.

public class DependencyDescriptor extends InjectionPoint {
  // Determine if the injection point is required
  public boolean isRequired() {
    // Check @Autowired required attribute
    if (!this.required) {
      return false;
    }
    if (this.field != null) {
      // hasNullableAnnotation determines presence of @Nullable
      return !(this.field.getType() == Optional.class || hasNullableAnnotation() ||
          (KotlinDetector.isKotlinReflectPresent() &&
           KotlinDetector.isKotlinType(this.field.getDeclaringClass()) &&
           KotlinDelegate.isNullable(this.field)));
    } else {
      return !obtainMethodParameter().isOptional();
    }
  }
  private boolean hasNullableAnnotation() {
    // Iterate over all annotations on the field
    for (Annotation ann : getAnnotations()) {
      // Only checks if the annotation name is "Nullable"
      if ("Nullable".equals(ann.annotationType().getSimpleName())) {
        return true;
      }
    }
    return false;
  }
}

The same logic works when @Nullable is placed on a method parameter:

@Autowired
public void setDao(@Nullable PersonDAO dao) {
  this.dao = dao ;
}

Summary: In Spring, the @Nullable annotation tells the container that a field or parameter may be null, preventing NoSuchBeanDefinitionException when the bean is absent.