debug:spring-boot

What this skill does

# Spring Boot Debugging Guide

You are an expert Spring Boot debugger. Follow this systematic approach to diagnose and resolve issues efficiently.

## Common Error Patterns

### 1. NoSuchBeanDefinitionException
**Symptoms:**
- "Field xyz required a bean of type 'X' that could not be found"
- "No qualifying bean of type 'X' available"

**Debugging Steps:**
1. Verify the class has `@Component`, `@Service`, `@Repository`, or `@Controller` annotation
2. Check if the class is in a package scanned by `@ComponentScan` (must be in or below `@SpringBootApplication` class package)
3. Verify `@Configuration` classes with `@Bean` methods are being loaded
4. Check for conditional annotations (`@ConditionalOnProperty`, `@Profile`) that might exclude the bean
5. Look for typos in qualifier names with `@Qualifier`

**Quick Fixes:**
```java
// Ensure main class is at root package
@SpringBootApplication
public class Application { ... }

// Explicit component scan if needed
@ComponentScan(basePackages = {"com.example.main", "com.example.other"})

// Check bean registration
@Autowired
private ApplicationContext context;
Arrays.stream(context.getBeanDefinitionNames()).forEach(System.out::println);
```

### 2. Application Failed to Start
**Symptoms:**
- "Web server failed to start. Port 8080 was already in use"
- "Application run failed"
- Context initialization errors

**Debugging Steps:**
1. Check for port conflicts: `lsof -i :8080` or `netstat -an | grep 8080`
2. Review full stack trace for root cause (scroll up past Spring banner)
3. Check database connectivity if using JPA
4. Verify all required environment variables are set
5. Look for missing dependencies in pom.xml or build.gradle

**Quick Fixes:**
```properties
# Change port if in use
server.port=8081

# Enable debug startup logging
debug=true
logging.level.org.springframework=DEBUG

# Fail fast on missing properties
spring.main.allow-bean-definition-overriding=false
```

### 3. Circular Dependency
**Symptoms:**
- "The dependencies of some of the beans in the application context form a cycle"
- "Requested bean is currently in creation"

**Debugging Steps:**
1. Read the cycle chain in error message (A -> B -> C -> A)
2. Identify which dependency can be broken
3. Consider if the design needs refactoring

**Quick Fixes:**
```java
// Option 1: Use @Lazy on one dependency
@Autowired
@Lazy
private ServiceB serviceB;

// Option 2: Use setter injection
private ServiceB serviceB;

@Autowired
public void setServiceB(ServiceB serviceB) {
    this.serviceB = serviceB;
}

// Option 3: Refactor to event-based communication
@EventListener
public void handleEvent(CustomEvent event) { ... }
```

### 4. JPA/Hibernate Issues
**Symptoms:**
- "No EntityManager with actual transaction available"
- LazyInitializationException
- "Table doesn't exist" / Schema validation errors
- N+1 query problems

**Debugging Steps:**
1. Enable SQL logging to see actual queries
2. Check `@Transactional` placement (must be on public methods)
3. Verify entity relationships and cascade types
4. Check database schema matches entity definitions

**Quick Fixes:**
```properties
# Enable SQL debugging
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

# Schema handling
spring.jpa.hibernate.ddl-auto=validate  # Recommended for debugging
spring.jpa.hibernate.ddl-auto=update    # Auto-update schema (dev only)
```

```java
// Fix LazyInitializationException
@Transactional(readOnly = true)
public Entity getWithChildren(Long id) {
    Entity e = repository.findById(id).orElseThrow();
    e.getChildren().size(); // Force initialization
    return e;
}

// Or use EntityGraph
@EntityGraph(attributePaths = {"children", "children.grandchildren"})
Optional<Entity> findById(Long id);
```

### 5. Security Configuration Problems
**Symptoms:**
- 403 Forbidden on all endpoints
- Authentication not working
- CORS errors
- CSRF token issues

**Debugging Steps:**
1. Enable security debug logging
2. Check filter chain order
3. Verify authentication provider configuration
4. Review SecurityFilterChain bean configuration

**Quick Fixes:**
```properties
# Enable security debugging
logging.level.org.springframework.security=DEBUG
logging.level.org.springframework.security.web.FilterChainProxy=DEBUG
```

```java
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/actuator/health").permitAll()
                .anyRequest().authenticated()
            )
            .csrf(csrf -> csrf.disable()) // Only for APIs with token auth
            .cors(Customizer.withDefaults());
        return http.build();
    }
}
```

### 6. Property Binding Failures
**Symptoms:**
- "Failed to bind properties under 'x.y.z'"
- "Could not resolve placeholder"
- Configuration values not being read

**Debugging Steps:**
1. Check property file location (src/main/resources)
2. Verify property name matches exactly (case-sensitive, hyphen vs camelCase)
3. Check active profiles (`spring.profiles.active`)
4. Verify `@ConfigurationProperties` prefix matches

**Quick Fixes:**
```java
// Debug property sources
@Autowired
private Environment env;

@PostConstruct
public void debugProperties() {
    System.out.println("Active profiles: " + Arrays.toString(env.getActiveProfiles()));
    System.out.println("Property value: " + env.getProperty("my.property"));
}

// Ensure @ConfigurationProperties is scanned
@EnableConfigurationProperties(MyProperties.class)
@SpringBootApplication
public class Application { ... }
```

```properties
# Add to see property resolution
logging.level.org.springframework.boot.context.properties=DEBUG
```

## Debugging Tools

### Spring Boot Actuator
Essential for runtime diagnostics:
```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
```

```properties
# Expose all actuator endpoints (dev only)
management.endpoints.web.exposure.include=*
management.endpoint.health.show-details=always
```

**Key Endpoints:**
- `/actuator/health` - Application health status
- `/actuator/beans` - All registered beans
- `/actuator/env` - Environment properties
- `/actuator/mappings` - Request mappings
- `/actuator/configprops` - Configuration properties
- `/actuator/conditions` - Auto-configuration report

### Remote JVM Debugging
```bash
# Maven
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"

# Gradle
./gradlew bootRun --debug-jvm

# Java directly
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar

# Docker Compose
environment:
  - JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
ports:
  - "5005:5005"
```

### Logback/Log4j2 Configuration
Create `src/main/resources/logback-spring.xml`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Debug specific packages -->
    <logger name="org.springframework.web" level="DEBUG"/>
    <logger name="org.hibernate.SQL" level="DEBUG"/>
    <logger name="com.yourapp" level="DEBUG"/>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>
```

### Spring Boot DevTools
```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <opti