Debugging Playbook

Root cause: Accessing a lazy collection outside of a transaction — the Hibernate session is closed.

Where to look: The line in YOUR code that accesses order.getItems(). Is it inside a @Transactional method? Or are you accessing it after the transaction has already committed (e.g., in a controller or DTO mapper)?

Fixes:

1. Move the access inside a @Transactional service method
2. Use a JOIN FETCH query: SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :id
3. Use a projection/DTO that fetches only what you need

BeanCreationException

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'orderService'
...
Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException
...
Caused by: org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type 'com.example.PaymentClient'

Root cause: A dependency can't be found. Follow the Caused by chain to the missing bean.

Checklist:

• Is the missing class annotated with @Service, @Component, @Repository?
• Is it in a package scanned by @SpringBootApplication? (Must be in a subpackage of the main class)
• Is there a @Profile condition preventing it from loading in this environment?
• Is there a @ConditionalOn* that evaluates to false?

Diagnose with Actuator:

curl http://localhost:8080/actuator/conditions | jq '.positiveMatches | keys'   # what loaded
curl http://localhost:8080/actuator/conditions | jq '.negativeMatches | keys'   # what didn't load

ContextRefreshException / Application fails to start

Application failed to start
  ...
Caused by: java.lang.IllegalStateException: Failed to load ApplicationContext

Checklist (in order):

1. Check the FULL stack trace — the root cause is buried deep
2. Check application.yml syntax — YAML is whitespace-sensitive
3. Check required properties: @Value("${some.property}") — is it set in config?
4. Check datasource config — can the app reach the database?
5. Check circular dependencies: The dependencies of some of the beans in the application context form a cycle

Find missing properties:

grep -r "@Value" src/main/java --include="*.java" | grep -v "test"
# Cross-reference with application.yml

NullPointerException in Spring Code

java.lang.NullPointerException: Cannot invoke "com.example.Order.getId()" because "order" is null
  at com.example.OrderService.processOrder(OrderService.java:83)

Java 17+ NPEs include the null reference in the message. Read it literally: order is null at line 83.

Common Spring causes:

• Repository returns Optional but code calls .get() without checking
• @Autowired field is null — the class was instantiated via new instead of Spring (not a bean)
• @MockBean not set up in a test — returns null by default

Spring Boot Actuator Debugging Endpoints

Enable for debugging (dev/staging only — never expose in prod without auth):

# application-local.yml