A class-name collision is one possible cause of a Kotlin Multiplatform framework integration failure involving SwiftUI: Kotlin package names do not become namespaces in the Objective-C-facing framework API. If two exported Kotlin classes share a name, Kotlin/Native may rename them, and its naming algorithm can change between Kotlin releases. Confirm what the framework actually exports before changing code; the title alone does not establish the cause of a particular build error.
Why Kotlin package names may not protect class names
Kotlin source code can contain classes with the same name in different packages. For example, separate packages might each define a class named Settings. But when Kotlin/Native exposes declarations through an Objective-C framework, the Kotlin package boundaries do not function as namespaces for those classes in the framework API. If both classes are exported into the same framework, their names can collide on that surface.
As an Amazon Associate I earn from qualifying purchases.
Kotlin/Native may resolve the conflict by renaming declarations in the generated Objective-C-facing API. The Kotlin documentation cautions that “This algorithm is not stable yet and can change between Kotlin releases.” That means a name observed in one generated framework should not be treated as a stable, intentional Swift API across Kotlin upgrades.
Recommended Free Tools
How to check whether this is your build problem
A SwiftUI or Xcode build failure is not, by itself, proof of a Kotlin name collision. Check the framework’s generated Objective-C header and the framework’s exported surface. Kotlin’s interoperability documentation describes how declarations are exposed to Objective-C and Swift; Apple’s documentation provides general context on generated headers and references between Swift declarations and Objective-C headers.
#1 Best Overall
- Find the generated framework header. Inspect the header produced for the framework that the Swift target imports. Look for the affected class name and any altered or disambiguated names.
- Trace declarations back to Kotlin. Check whether classes with the same Kotlin class name come from different packages and whether both are visible to the Swift-facing framework.
- Check framework export settings. Exported dependency APIs can be included in a framework, so inspect which dependencies are exported—not just the declarations in the app’s main Kotlin source set. Kotlin documents framework creation and dependency export in Build final native binaries.
- Compare the header with the failing reference. Confirm whether Swift code or another header consumer refers to a name that the generated framework actually exposes. If the names line up, investigate the error on its own terms; other SwiftUI, Xcode, or framework integration problems need separate diagnosis.
For the interoperability details, see Kotlin’s Interoperability with Swift/Objective-C. Apple’s Importing Swift into Objective-C is relevant to generated-header context, but does not identify SwiftUI as the cause of Kotlin class-name collisions.
What to change when two exported classes collide
Rename the conflicting Kotlin classes
Kotlin’s documented workaround is direct: “To work around this issue, rename the conflicting Kotlin classes in the framework.” Give the Kotlin declarations distinct names, then regenerate the framework and inspect the header again. This addresses the collision at its source and avoids relying on an automatically chosen exported name that may change between Kotlin releases.
Rank #2
Renaming changes the Swift-facing API names. Search Swift call sites and any other consumers of the generated header, then update references to match the regenerated framework. Check the header after the change rather than assuming a source-level rename produced the expected exported spelling.
Hide a declaration only if Swift does not need it
@HiddenFromObjC can keep a declaration out of the Objective-C and Swift surface while leaving it visible to other Kotlin modules. Kotlin’s internal visibility limits access to the compilation module. Either can reduce what enters the exposed API, but neither is appropriate when Swift needs to use that declaration. Kotlin documents these controls in its Swift/Objective-C interoperability guidance.
Do not assume a framework-name change fixes the collision
Kotlin class names imported into Objective-C receive a prefix derived from the framework name. That naming fact does not establish that changing the framework name resolves two same-named Kotlin declarations inside the same framework. Kotlin’s stated collision workaround is to rename the conflicting Kotlin classes, not to rename the framework.
What framework exports change in the investigation
A framework can contain Kotlin declarations and APIs from dependencies selected for export. Consequently, two classes that look unrelated in the main project may both reach the same framework through exported dependencies. Check the actual export configuration and the resulting header before deciding which declaration to rename or exclude.
Kotlin also supports transitive dependency export, which can bring additional APIs into the framework. The Kotlin build documentation discourages transitive export in most cases because of compilation-time and binary-size effects. For a name-collision investigation, its practical significance is that a broader exported surface can introduce declarations that need to be considered.
Is Swift export a drop-in alternative?
Kotlin’s Swift export preserves package structure and supports separate Swift modules, which speaks directly to the namespace problem. However, Kotlin labels Swift export Alpha; the documentation lists limitations and says it currently requires direct integration. Treat it as an evolving option to evaluate against your project’s integration and feature requirements, not as a universal or immediate repair for an existing framework build. See Interoperability with Swift using Swift export for the current documented status and constraints.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
