Spring Boot Production Troubleshooting Guide

// LEAK: static map with no eviction
private static final Map<String, UserData> cache = new HashMap<>();

// FIX: use Caffeine with size and TTL
@Bean
public Cache<String, UserData> userCache() {
    return Caffeine.newBuilder()
        .maximumSize(10_000)
        .expireAfterWrite(Duration.ofMinutes(30))
        .build();
}

// LEAK: RequestContext not cleared after request
private static ThreadLocal<RequestContext> context = new ThreadLocal<>();

// FIX: always remove in a finally block or servlet filter
try {
    context.set(new RequestContext(request));
    doFilter(request, response, chain);
} finally {
    context.remove(); // CRITICAL — thread goes back to pool, not destroyed
}

// LEAK: registers listener but never removes it
applicationContext.addApplicationListener(myListener);

// FIX: use @EventListener (Spring manages lifecycle)
@EventListener
public void handleOrderCreated(OrderCreatedEvent event) { ... }
// Or implement ApplicationListener and let Spring manage it as a bean

// LEAK: processing 1M rows in one transaction loads them all into session cache
@Transactional
public void processAll() {
    List<Order> orders = repo.findAll(); // 1M objects in session cache
    orders.forEach(this::process);
}

// FIX: process in batches, clear session cache
@Transactional
public void processAll(EntityManager em) {
    int batch = 500;
    for (int i = 0; ; i += batch) {
        List<Order> page = repo.findPage(i, batch);
        if (page.isEmpty()) break;
        page.forEach(this::process);
        em.flush();
        em.clear(); // clear session cache
    }
}

// Only mark expensive beans as lazy
@Lazy
@Bean
public ExpensiveReportEngine reportEngine() {
    return new ExpensiveReportEngine(); // Only created when first needed
}

// Or lazy-inject a dependency
@Autowired
@Lazy
private ExpensiveService expensiveService;

// BAD: scans entire com.mycompany tree (thousands of classes)
@SpringBootApplication // defaults to scanning everything under the main class package
public class App { }

// BETTER: narrow the scan
@SpringBootApplication(scanBasePackages = {
    "com.mycompany.app.web",
    "com.mycompany.app.service",
    "com.mycompany.app.repository"
})
public class App { }

// LEAK: manually opens connection, but exception prevents close
public Order process(Long id) {
    Connection conn = dataSource.getConnection(); // checked out
    // ... exception thrown here ...
    conn.close(); // never reached
}

// FIX: use try-with-resources
try (Connection conn = dataSource.getConnection()) {
    // connection auto-closed
}
// OR better: let Spring's @Transactional manage it
@Transactional
public Order process(Long id) { ... } // connection returned at end of transaction

// LEAK: transaction spans an external HTTP call — holds DB connection while waiting
@Transactional
public Order processOrder(Long id) {
    Order order = repo.findById(id);      // gets DB connection
    paymentClient.charge(order);          // HTTP call — could take 5s!
    repo.save(order);                     // connection held the whole time
    return order;
}

// FIX: minimize transaction scope
public Order processOrder(Long id) {
    Order order = loadOrder(id);              // short transaction
    PaymentResult result = paymentClient.charge(order); // outside transaction
    return saveResult(order, result);         // short transaction
}

@Transactional(readOnly = true)
private Order loadOrder(Long id) { return repo.findById(id).orElseThrow(); }

@Transactional
private Order saveResult(Order order, PaymentResult result) { ... }

// Mark readiness as DOWN during graceful shutdown
@Bean
public ApplicationAvailability availability() {
    return ApplicationAvailability.get(applicationContext);
}

// Manually change readiness state (e.g., before maintenance)
@Autowired
private ApplicationEventPublisher publisher;

public void goOffline() {
    publisher.publishEvent(new AvailabilityChangeEvent<>(
        this, ReadinessState.REFUSING_TRAFFIC));
}

@Component
public class ExternalServiceHealthIndicator implements HealthIndicator {

    private final ExternalServiceClient client;

    public ExternalServiceHealthIndicator(ExternalServiceClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        try {
            // Keep health checks fast — timeout < 3s
            boolean available = client.ping(Duration.ofSeconds(2));
            if (available) {
                return Health.up()
                    .withDetail("url", client.getBaseUrl())
                    .withDetail("responseTime", "< 2s")
                    .build();
            } else {
                return Health.down()
                    .withDetail("reason", "ping timeout")
                    .build();
            }
        } catch (Exception ex) {
            return Health.down(ex)
                .withDetail("url", client.getBaseUrl())
                .build();
        }
    }
}

// BAD: default @Async with SimpleAsyncTaskExecutor
@Async
public CompletableFuture<String> doWork() { ... }

// GOOD: configure a bounded thread pool
@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);          // always-alive threads
        executor.setMaxPoolSize(50);           // expand up to 50 under load
        executor.setQueueCapacity(500);        // queue up to 500 tasks before rejecting
        executor.setThreadNamePrefix("async-worker-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        // CallerRunsPolicy: if pool full, caller thread executes the task (backpressure)
        executor.initialize();
        return executor;
    }

    @Override
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
        return (ex, method, params) ->
            log.error("Uncaught async exception in {}: {}", method.getName(), ex.getMessage(), ex);
    }
}

@Configuration
@EnableAsync
public class AsyncConfig {

    // CPU-bound work — #threads = number of cores
    @Bean("cpuBoundExecutor")
    public TaskExecutor cpuBoundExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(Runtime.getRuntime().availableProcessors());
        executor.setMaxPoolSize(Runtime.getRuntime().availableProcessors());
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("cpu-");
        executor.initialize();
        return executor;
    }

    // I/O-bound work — more threads since they mostly wait
    @Bean("ioBoundExecutor")
    public TaskExecutor ioBoundExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(50);
        executor.setMaxPoolSize(200);
        executor.setQueueCapacity(1000);
        executor.setThreadNamePrefix("io-");
        executor.initialize();
        return executor;
    }
}

// Use the named executor
@Async("ioBoundExecutor")
public CompletableFuture<String> callExternalApi() { ... }

// In main class or a test setup
@SpringBootApplication
public class App {
    public static void main(String[] args) {
        BlockHound.install(); // throws BlockingOperationError when blocking call detected on reactor thread
        SpringApplication.run(App.class, args);
    }
}

// BAD: blocking call inside a reactive chain
Mono<String> result = Mono.fromCallable(() -> jdbcTemplate.queryForObject(...)); 
// This will block the reactor thread!

// GOOD: offload to a bounded elastic scheduler
Mono<String> result = Mono.fromCallable(() -> jdbcTemplate.queryForObject(...))
    .subscribeOn(Schedulers.boundedElastic()); // switches to I/O thread pool

// Servlet filter to inject trace context
@Component
@Order(1)
public class TraceContextFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
            throws ServletException, IOException {

        String requestId = Optional.ofNullable(req.getHeader("X-Request-ID"))
            .orElse(UUID.randomUUID().toString());

        // Extract from OpenTelemetry/Zipkin headers if present
        String traceId = req.getHeader("X-B3-TraceId");
        if (traceId == null) traceId = UUID.randomUUID().toString().replace("-", "");

        MDC.put("requestId", requestId);
        MDC.put("traceId", traceId);
        MDC.put("path", req.getRequestURI());

        res.setHeader("X-Request-ID", requestId);

        try {
            chain.doFilter(req, res);
        } finally {
            MDC.clear(); // MUST clear — thread goes back to pool
        }
    }
}

// Propagate MDC to async tasks
@Async
public void processAsync(String orderId) {
    // MDC is thread-local — it's empty in the async thread
    // Use Spring's TaskDecorator to propagate it
}

// Fix: configure MDC-aware decorator
@Bean
public ThreadPoolTaskExecutor asyncExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(10);
    executor.setTaskDecorator(runnable -> {
        Map<String, String> contextMap = MDC.getCopyOfContextMap();
        return () -> {
            try {
                if (contextMap != null) MDC.setContextMap(contextMap);
                runnable.run();
            } finally {
                MDC.clear();
            }
        };
    });
    executor.initialize();
    return executor;
}

@Component
public class SamplingHealthCheckFilter extends OncePerRequestFilter {

    private final AtomicLong counter = new AtomicLong();

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
            throws ServletException, IOException {

        // Only log 1 in 100 health check requests
        if (req.getRequestURI().startsWith("/actuator/health")) {
            if (counter.incrementAndGet() % 100 != 0) {
                chain.doFilter(req, res);
                return; // skip logging
            }
        }
        chain.doFilter(req, res);
    }
}

// BAD — PII in logs
log.info("Processing payment for user {} with card {}", user.getEmail(), card.getNumber());

// GOOD — mask sensitive data
log.info("Processing payment for user {} with card ending {}", 
    user.getId(),  // use ID, not email
    card.getNumber().substring(card.getNumber().length() - 4)); // last 4 only

// Even better — a masking helper
public class LogMasker {
    public static String maskCard(String number) {
        return "****-****-****-" + number.substring(number.length() - 4);
    }
    public static String maskEmail(String email) {
        int at = email.indexOf('@');
        return email.charAt(0) + "***" + email.substring(at);
    }
}