Troubleshooting Common Issues
1. Resolving Bean Creation Exceptions
| Error | Fix |
|---|---|
NoSuchBeanDefinitionException |
Add @Component/@Bean; check component scan packages |
NoUniqueBeanDefinitionException |
Use @Qualifier or @Primary |
BeanInstantiationException |
Constructor failure — check root cause |
UnsatisfiedDependencyException |
Missing collaborator bean |
2. Fixing Circular Dependency Issues
Example: Fix circular dependency with @Lazy
// Avoid: A → B → A constructor injection (fails by default in Boot 2.6+)
// Fix 1: Refactor — extract shared logic into 3rd bean
// Fix 2: Use setter injection on one side
// Fix 3: @Lazy on the back-edge dependency
public A(@Lazy B b) { this.b = b; }Warning:
spring.main.allow-circular-references=true "fixes" the
symptom but masks design problems.3. Debugging Auto-Configuration Problems
| Tool | Use |
|---|---|
--debug flag |
Print auto-config report |
/actuator/conditions |
Matched / unmatched conditions |
@SpringBootApplication(exclude = {X.class}) |
Disable specific autoconfig |
spring.autoconfigure.exclude |
Property-based exclusion |
4. Resolving Port Already in Use (server.port)
Example: Find port conflict and use random port
# Find process holding the port
lsof -i :8080
# Or use random port
SERVER_PORT=0 java -jar app.jar
# Or assign dynamically
server.port=0 # in application.yml5. Fixing ClassNotFoundException and NoClassDefFoundError
| Cause | Fix |
|---|---|
| Missing dependency | Add to pom/gradle |
| Version conflict | mvn dependency:tree + exclusions |
| Provided/test scope only | Change to compile/runtime |
| Static initializer failed (NoClassDefFoundError after first OK) | Check root-cause exception trace |
6. Debugging Transaction Not Working Issues
| Cause | Fix |
|---|---|
| Self-invocation (proxy bypassed) | Call from another bean, or use AspectJ |
| Method not public | Make @Transactional method public |
| Checked exception | Add rollbackFor = Exception.class |
| Wrong TransactionManager | Specify transactionManager = "..." |
| Non-transactional engine (MyISAM) | Use InnoDB |
7. Resolving Database Connection Pool Exhaustion
| Symptom | Action |
|---|---|
| HikariPool — Connection is not available | Investigate leaks & long queries |
| Set leak detection | spring.datasource.hikari.leak-detection-threshold=30000 |
| Increase pool size | maximum-pool-size (carefully — DB has limits) |
| Use read replicas | Offload read traffic |
8. Fixing CORS Errors in Browser
Example: Global CORS mapping via WebMvcConfigurer
@Configuration
public class CorsConfig implements WebMvcConfigurer {
@Override public void addCorsMappings(CorsRegistry r) {
r.addMapping("/api/**")
.allowedOrigins("https://app.example.com")
.allowedMethods("GET","POST","PUT","DELETE")
.allowCredentials(true)
.maxAge(3600);
}
}Note: When using Spring Security, also expose CORS via
http.cors(Customizer.withDefaults()).9. Debugging 404 Not Found Errors
| Check | Detail |
|---|---|
| Controller in scanned package | Below @SpringBootApplication |
| Path mapping | Match HTTP method + URL exactly |
| Servlet context path | server.servlet.context-path |
| Static resource handler | Files under src/main/resources/static |
| Trailing slash | Spring 6 disabled trailing-slash match by default |
| logging.level.org.springframework.web=DEBUG | See request mapping resolution |
10. Resolving Memory Leaks and OutOfMemoryError
| Type | Diagnosis |
|---|---|
| Java heap space | Heap dump → MAT/VisualVM |
| Metaspace | ClassLoader leak (devtools, hot reload) |
| Direct buffer | Netty/NIO buffers; check -XX:MaxDirectMemorySize |
| GC overhead limit | Heap too small for workload |
Example: JVM flags for heap dump on OOM
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/heap.hprof11. Troubleshooting Slow Application Startup
| Cause | Mitigation |
|---|---|
| Heavy auto-configuration | /actuator/startup to identify slow beans |
| JPA scanning all entities | Restrict basePackages |
| Eager init of expensive beans | spring.main.lazy-initialization=true |
| Slow DNS | Configure name resolution / hostname cache |
| Large classpath scan | AOT processing or native image |
12. Fixing LazyInitializationException
| Strategy | Trade-off |
|---|---|
JOIN FETCH in JPQL |
Best — explicit per query |
@EntityGraph |
Declarative fetch graph |
| DTO projection | Avoid entities outside session |
| OSIV (Open Session In View) | Default ON — antipattern; disable: spring.jpa.open-in-view=false |
Warning: Disabling OSIV is recommended, but requires fixing all lazy-loading
code paths first.