Boundary Pitfalls

When Java returns a value, Kotlin doesn't know if it can be null, so it trusts you. If you treat it as non-null and it actually is null, you only crash later when you use it.

Kotlin turns a companion object into a static field named Companion plus a nested class. From Java you call MyClass.Companion.method(), unless the member is annotated @JvmStatic, which lets you call MyClass.method() directly.

A single Kotlin property turns into several Java elements (field, getter, setter, constructor parameter). A use-site target like @field: tells the compiler which of those elements the annotation should land on.

Put @JvmName with a different name on at least one of the clashing functions. That gives each a unique method name in the compiled code, so the JVM no longer sees a duplicate.

All of them crash if the value is null, but requireNotNull/checkNotNull let you attach a clear message and throw a meaningful exception, while !! throws a bare NullPointerException with no explanation.

The bare annotation landed on the constructor parameter, but the framework reads the backing field by reflection. Since the field has no annotation, nothing happens. Prefixing with @field: puts it where the framework looks.

Kotlin's internal means 'visible only inside this module'. To keep Java from calling it casually, Kotlin renames it in the compiled bytecode by adding a suffix, so the Java-visible name no longer matches the Kotlin name.

A Kotlin property quietly generates a getter method like getX(). If you also write a function named getX(), both produce the same JVM method, so they clash. Rename one with @JvmName, or rename the function.

Add @JvmName("cleanName") to the function. That overrides the compiler's mangled name with the one you pick, so Java sees a normal method. The risk is you might now collide with another method that has the same JVM signature.

An inline value class disappears at runtime — it's replaced by its underlying type (here Long). To keep functions that take value classes apart from ones that take the raw type, Kotlin adds a hash suffix to the method name, so Java sees a mangled name instead of pay.

Add nullability annotations like @Nullable or @NotNull on the Java side. Kotlin reads them and turns the value into a real nullable or non-null type, bringing back compile-time checks.

Java has no default arguments, so Kotlin compiles a function with defaults into the real method plus a synthetic $default helper. The helper takes an extra bitmask telling it which arguments were omitted, then fills in the defaults. Java should normally use @JvmOverloads instead.

WhenMappings is a hidden helper class Kotlin creates when you switch over an enum (or sealed) in a when. It holds an int[] mapping each enum constant's ordinal to a small table index so the compiled switch is a fast tableswitch.

@get:JvmName("...") renames the getter method that Java sees, without changing the Kotlin property name. You use it to fix or customize the Java-facing accessor name, e.g. to avoid awkward or clashing generated names.

Yes. @JvmOverloads expands a function with default values into several Java overloads. If those generated overloads, after erasure, match an existing function's signature, you get a clash. You fix it by renaming with @JvmName or removing the overlap.

The suffix on an internal method contains the module's name. If the module name changes, the mangled method name changes too, so anything that linked against the old name breaks. Internal members are not stable API — don't rely on their JVM names.

A null can also hide inside a Java list, map, or array element, or in a generic type argument. Kotlin trusts the whole container as non-null, so the crash pops up only when you read the null element.

When an inner/nested or companion context needs a private member of an outer class, Kotlin used to generate hidden access$ bridge methods because separate JVM classes can't touch each other's privates. Newer bytecode targets use nestmates instead, so fewer of these appear.

If you omit the target, the compiler picks the first applicable one from param, then property, then field. @param: and @field: are real Java elements reflection can see; @property: is Kotlin-only metadata that plain Java can't read.

An inline value class is erased to its underlying type on the JVM, so two functions taking different value classes over the same base type would clash. Kotlin auto-mangles their names to avoid that; @JvmName is for the generic-collection case it can't auto-fix.

$VALUES is a hidden static array holding every enum constant once. values() returns a defensive copy of it each call; valueOf() looks a name up in it. Kotlin's newer entries property returns a cached immutable list instead, avoiding the per-call copy.

@receiver: puts an annotation on the receiver parameter of an extension function or property (the hidden 'this' parameter). @delegate: puts it on the synthetic field that stores a delegated property's delegate instance.

Keep the value classes for Kotlin callers, but give Java a separate, plain-typed public API. Don't let Java touch internal members or value-class-typed methods directly; expose facade functions that take primitive/boxed types and have stable names.

When you override a Java method, Kotlin lets you pick nullable or non-null for the platform-typed parts. Choose nullable if callers might pass null. As a team, annotate Java, wrap third-party APIs, and turn unknown values nullable at the edge.