debug-spring-boot_skill

Overview

This skill helps you debug Spring Boot applications systematically, focusing on bean problems, startup failures, JPA/Hibernate issues, security misconfigurations, property binding errors, and runtime diagnostics. It provides a structured four-phase workflow—gather, reproduce, diagnose, fix—and practical commands, configuration snippets, and quick fixes you can apply immediately. Use it to reduce time-to-resolution for common Spring Boot error patterns and to improve confidence when troubleshooting production and development incidents.

How this skill works

The skill inspects error symptoms and maps them to targeted diagnostic steps: component scanning and bean registration checks for NoSuchBeanDefinitionException, port and dependency checks for startup failures, and transaction/SQL logging for JPA issues. It surfaces Actuator endpoints and JVM debugging approaches to gather runtime state, recommends targeted test isolates and logging to reproduce and diagnose, and suggests concrete code/config changes and verification steps to fix and prevent regressions. It also provides quick reference commands for Maven, Gradle, Docker, Kubernetes, and JVM tooling.

When to use it

• Application fails to start or reports context initialization errors
• NoSuchBeanDefinitionException or bean wiring issues occur
• JPA/Hibernate problems: LazyInitializationException, N+1 queries, or schema mismatches
• Security issues produce 403 Forbidden, CORS, or CSRF token errors
• Property binding failures or missing configuration values
• You need runtime diagnostics via Actuator or remote JVM debugging

Best practices

• Enable and use Actuator endpoints in development for beans, env, and mappings
• Run minimal isolated tests to reproduce issues before changing production code
• Enable SQL and security debug logs only in safe environments to avoid sensitive output
• Prefer constructor injection, avoid static @Autowired, and apply @Lazy or setter injection to break cycles
• Use @Transactional on public methods and validate entity mappings against the DB schema
• Version-control and automate configuration for consistent profiles and property resolution

Example use cases

• Resolve NoSuchBeanDefinitionException by checking component scan and printing context beans
• Fix port conflicts and dependency startup failures using log inspection and server.port override
• Diagnose LazyInitializationException by adding @Transactional or using EntityGraph queries
• Investigate 403 errors by enabling Spring Security debug logging and reviewing the SecurityFilterChain
• Use remote JVM debugging and thread dumps to diagnose deadlocks or high-latency threads
• Expose actuator endpoints in staging to inspect runtime bean wiring and environment properties