Skip to main content

Mangled JVM names in public API

DiagnosticMANGLED_JVM_NAME_PUBLIC_API
Default severityError
Applies toJVM compilations only
Gradle propertymangledJvmNamePublicApi
Exemption@IntentionallyMangledJvmName

What it reports​

Functions, properties, and constructors in the public API whose JVM name changes because the signature uses a value class:

  • In a value parameter, extension receiver, or context parameter.
  • As a member's return type.
  • As a mutable property's type, which affects its setter even at the top level.
@JvmInline
public value class UserId(
public val raw: String,
)
public fun take(id: UserId) { }

Rationale​

A mangled JVM method name such as take-<hash> is invalid in Java source.

For constructors with value-class parameters, the compiler generates a private constructor and a synthetic constructor that Java source can't call.

Use @JvmName to give the function a valid name in Java source.

Don't​

public fun take(id: UserId) { }

Do​

@JvmName("take")
public fun take(id: UserId) { }

@JvmExposeBoxed generates boxed variants for Java callers alongside the mangled variants. Constructors need this annotation because the compiler doesn't accept @JvmName on them.

Don't​

public class Wallet(
public val id: UserId
)

Do​

@OptIn(ExperimentalStdlibApi::class)
@JvmExposeBoxed
public class Wallet(
public val id: UserId,
)

Don't​

public class Ledger {
public fun current(): UserId = UserId("x")
}

Do​

public class Ledger {
@JvmName("current")
public fun current(): UserId = UserId("x")
}

Notes​

  • Rename property accessors with @get:JvmName and @set:JvmName. The check treats each accessor separately. A rename or @JvmSynthetic on one accessor doesn't exempt the other.
  • Open and abstract members don't support @JvmName or boxed variants. If Java callers need access, remove the value class from the signature.
  • Value classes in type arguments, such as List<UserId>, don't cause JVM name mangling.
  • If a top-level function or getter uses a value class only as its return type, its JVM name doesn't change.
  • The check skips members and constructors of the value class itself.
  • The plugin checks suspend functions with Kotlin-only API without JvmSynthetic.
  • The check skips overrides, @JvmSynthetic functions and accessors, and @PublishedApi internal declarations.

Exemption​

If this is intended, apply @IntentionallyMangledJvmName to the declaration or an enclosing class.

Use the exemption when the declaration is part of the API design or must stay for backwards compatibility.

@IntentionallyMangledJvmName(reason = ExemptionReason.API_DESIGN)
public fun take(id: UserId) { }

Configuration​

build.gradle.kts
apiWatchdog {
javaInterop {
mangledJvmNamePublicApi = WatchdogSeverity.ERROR
}
}

javaInterop { enabled = false } disables all Java interop checks.

For a direct compiler call:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=MANGLED_JVM_NAME_PUBLIC_API:error

See also​