kotlin-spring-proxy-compatibility

Diagnose Kotlin Spring AOP proxy issues affecting annotation interception.

14|1|Updated Mar 6, 2026
One-click install
npx skills add https://github.com/Kotlin/kotlin-backend-agent-skills --skill kotlin-spring-proxy-compatibility
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: kotlin-spring-proxy-compatibility
Source: https://github.com/Kotlin/kotlin-backend-agent-skills/tree/main/.agents/skills/kotlin-spring-proxy-compatibility
Command: npx skills add https://github.com/Kotlin/kotlin-backend-agent-skills --skill kotlin-spring-proxy-compatibility

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Diagnose and prevent Kotlin + Spring proxy failures around AOP annotations such as @Transactional, @Cacheable, @Async, method security, retry, configuration proxies, and JPA entity requirements. Use when AOP annotations appear to do nothing, transactional or cache behavior is inconsistent, compiler plugins may be missing, self-invocation is suspected, or Kotlin final-by-default semantics may break Spring behavior.

Core Features & Use Cases

  • Analyze whether a proxy should exist and whether a call crosses a proxy boundary for Kotlin Spring beans.
  • Inspect configuration plugins (e.g., Kotlin plugin.spring), proxy strategies (interface vs class proxies), and Kotlin final/open semantics to identify root causes.
  • Propose minimal, safe fixes and design considerations to ensure proper interception in production.

Quick Start

Provide the Kotlin Spring class and context triggering the issue so you can determine why AOP interception is not occurring and propose the safest fix.

Frequently Asked Questions about kotlin-spring-proxy-compatibility

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why is my @Transactional annotation not working in a Kotlin Spring project?

Kotlin Spring @Transactional interception often fails due to final-by-default classes, missing kotlin-spring compiler plugins, or self-invocation bypassing proxy boundaries. Diagnosing proxy strategy and class visibility identifies the root cause for a safe production fix.

How do I fix Spring AOP annotations like @Cacheable and @Async not intercepting in Kotlin?

Fixing Kotlin Spring AOP interception requires verifying the kotlin-spring plugin is active, opening classes or using interface proxies, and eliminating internal self-invocation to ensure annotations like @Cacheable and @Async cross proxy boundaries correctly.

Does Kotlin final-by-default behavior break Spring proxy-based AOP?

Kotlin final-by-default behavior prevents Spring from creating CGLIB class proxies, silently breaking AOP. Applying the kotlin-spring plugin opens classes for interception, restoring expected proxy behavior for transactional and caching annotations.

What is the best way to diagnose self-invocation issues in Spring AOP with Kotlin?

Diagnosing Spring AOP self-invocation in Kotlin involves tracing method calls to verify if they cross proxy boundaries. Internal calls bypass interception, so analyzing call flows and proxy strategy exposes where transactional or cache behavior is lost.

When should I use interface proxies versus class proxies in Kotlin Spring applications?

Choose interface proxies for Kotlin Spring when bean interfaces exist to avoid final class limitations, but class proxies are needed when intercepting concrete classes. Validating the configured proxy strategy ensures consistent AOP behavior across your project.