Skip to main content

Kotlin-only API without JvmSynthetic

DiagnosticKOTLIN_ONLY_API_WITHOUT_JVM_SYNTHETIC
Default severityError
Applies toJVM compilations only
Gradle propertykotlinOnlyApiWithoutJvmSynthetic
Exemption@IntentionallyKotlinOnlyApi

What it reports​

Functions in the public API with one of these shapes:

  • A suspend function.
  • An inline function with a reified type parameter.
  • A value or context parameter with a suspend function type, a function type with a receiver or context parameters, or a Unit-returning function type. This includes vararg element types.
public suspend fun load(key: String) { }

Rationale​

Java sees an extra Continuation parameter on suspend functions. Calls to reified functions fail at runtime. Kotlin function types also expose Java-specific constraints:

  • Suspend callbacks get an extra Continuation parameter, so a Java lambda must implement the coroutine protocol itself.
  • Receiver and context callbacks take the receiver and the context values as explicit leading arguments.
  • Unit callbacks must return Unit.INSTANCE.

@JvmSynthetic hides these functions from Java source. For Java callers, add a blocking or CompletableFuture alternative for suspend functions, or a fun interface for callbacks.

Don't​

public suspend fun refresh(key: String) { }

Do​

@JvmSynthetic
public suspend fun refresh(key: String) { }

Don't​

public inline fun <reified T> instantiate(): T? = null

Do​

@JvmSynthetic
public inline fun <reified T> instantiate(): T? = null

Don't​

public fun onEach(action: (Int) -> Unit) { }

Do​

public fun interface Action {
public fun doAction(value: Int)
}
public fun onEach(action: Action) { }

Notes​

  • The check skips abstract functions, interface members, overrides, constructors, and members of value classes.
  • The check skips @JvmSynthetic and @PublishedApi internal functions.
  • Non-suspend functions with a mangled signature belong to Mangled JVM names in public API. When @JvmName or @JvmExposeBoxed resolves the mangling, this check reports the Kotlin-only shape. Suspend functions stay with this check even when the compiler mangles their signature.

Exemption​

If this is intended, apply @IntentionallyKotlinOnlyApi to the function or an enclosing class.

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

@IntentionallyKotlinOnlyApi(reason = ExemptionReason.API_DESIGN)
public fun onEach(action: (Int) -> Unit) { }

Configuration​

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

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

For a direct compiler call:

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

See also​