How to Check Free Disk Space in Kotlin Multiplatform (KMP)

How Did We Encounter the Missing Disk Space API in Kotlin Multiplatform?

While working on a distributed edge computing platform for the logistics and supply chain industry, we faced a critical architectural constraint. The system was designed to operate offline in massive warehouses, caching large inventory payloads locally before syncing them back to a central server. We utilized Kotlin Multiplatform (KMP) to share our core business and synchronization logic across Android barcode scanners, desktop admin panels (JVM/Windows), embedded Linux gateways (Native), and web dashboards (JS).

During peak inventory periods, our automated telemetry alerted us to localized application crashes and corrupted SQLite databases on certain devices. We realized the devices were running out of local storage mid-sync. The obvious fix was to check the available disk space before initiating large payload downloads. In a standard JVM environment, calling java.io.File(“.”).freeSpace is trivial. However, when trying to execute this from our common KMP codebase, we quickly discovered that Kotlin Multiplatform does not natively provide a unified, portable API for hardware-level file system metrics.

This oversight in our cross-platform storage strategy led to failed edge node synchronizations. We needed a robust, KMP-compatible solution to read available disk space seamlessly across all target environments. This challenge inspired this article, detailing how engineering teams can navigate platform-specific hardware APIs in a KMP architecture.

Why Is Cross-Platform Storage Management Crucial for Edge Applications?

The business use case required absolute resilience. Warehouse operators could not afford to lose scanning progress due to out-of-storage exceptions. The core synchronization engine sat entirely in the commonMain module of our KMP project. To maintain a clean architecture, the synchronization logic needed a simple boolean answer: “Do we have enough local space to safely commit a 50MB payload?”

The issue surfaced because edge devices in logistics have highly variable hardware. Android devices might have gigabytes of space, while a specialized embedded Linux scanner might have only a few megabytes of writable flash memory. Furthermore, the web dashboard needed to utilize browser storage quotas without violating security sandboxes. When enterprise teams look to hire kotlin developers for multiplatform applications, handling these hardware variations abstractly without polluting the shared business logic is a fundamental requirement.

What Happened When We Tried to Read Free Disk Space in Kotlin Multiplatform?

Initially, the failure logs were scattered. On JVM targets, we saw standard IOExceptions detailing “No space left on device”. On Native Linux targets, the application would simply abort due to segmentation faults when writing to a full memory block. On the JS target, the browser silently dropped IndexedDB writes, causing silent data loss.

The architectural oversight was assuming that a multiplatform library like kotlinx-io or similar standard wrappers would automatically expose disk capacity. They do not. KMP excels at sharing logic, but when it interacts with the host operating system, it heavily relies on the expect/actual mechanism. Because reading disk space involves vastly different system calls—POSIX on Linux, Win32 APIs on Windows, JVM File APIs on Android/Desktop, and Web Storage APIs in the browser—we had an integration bottleneck.

How Did We Evaluate Solutions for Native and JS File Systems?

Our diagnostic process involved mapping out the capabilities and limitations of each target platform. We knew we had to bridge the gap using Kotlin’s expect/actual pattern, but we had to decide on the structural design. Since JS storage APIs are inherently asynchronous, our shared function had to be designed as a coroutine. We evaluated several architectural approaches.

Did We Consider Using Third-Party File System Libraries like Okio?

We initially looked into standardizing our file I/O around Square’s Okio, which is excellent for KMP file manipulation. However, while Okio handles reading, writing, and paths across platforms efficiently, it abstracts away the raw file system descriptors necessary to query underlying partition capacities. Extending Okio to support disk space queries would require writing custom JNI and Native bindings anyway, defeating the purpose of an off-the-shelf solution.

What About Calling System Shell Commands via expect/actual?

Another approach we considered for Native targets was executing shell commands (like df -k on Linux or dir on Windows) and parsing the string output. While this is a quick fix, it is highly brittle. Parsing string outputs from shell commands introduces risks around localization, varying OS versions, and elevated permission requirements. When you hire backend developers for scalable systems, relying on shell command parsing for core logic is generally recognized as a fragility anti-pattern.

Could We Bypass the JS Limitation Using Browser Quota APIs?

For the JavaScript target, direct disk access is strictly prohibited by browser security models. We considered gracefully degrading the feature (e.g., always returning a massive number to bypass checks). Instead, we utilized the navigator.storage.estimate() API. It doesn’t give OS-level disk space, but it provides the quota available to that specific domain origin, which perfectly satisfied the business requirement: knowing if the app is allowed to save more data.

How Can You Implement a Portable Disk Space Checker in KMP?

The final implementation leverages Kotlin coroutines to accommodate the asynchronous nature of JavaScript, while using synchronous system calls wrapped in I/O dispatchers for JVM and Native targets.

1. The Common Expectation (commonMain)

// commonMain/src/commonMain/kotlin/StorageUtils.kt
expect suspend fun getFreeDiskSpaceKb(path: String = "."): Long

2. The JVM Implementation (jvmMain / androidMain)

// jvmMain/src/jvmMain/kotlin/StorageUtils.kt
import java.io.File
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
actual suspend fun getFreeDiskSpaceKb(path: String): Long {
    return withContext(Dispatchers.IO) {
        val file = File(path)
        if (file.exists()) {
            file.freeSpace / 1024L
        } else {
            -1L // Path does not exist
        }
    }
}

3. The Native Implementation – Linux / macOS (nativeMain)

// linuxX64Main/src/linuxX64Main/kotlin/StorageUtils.kt
import kotlinx.cinterop.*
import platform.posix.*
actual suspend fun getFreeDiskSpaceKb(path: String): Long {
    return memScoped {
        val stat = alloc<statvfs>()
        if (statvfs(path, stat.ptr) == 0) {
            // f_bavail is free blocks for unprivileged users
            // f_frsize is fragment size
            val freeBytes = stat.f_bavail.toLong() * stat.f_frsize.toLong()
            freeBytes / 1024L
        } else {
            -1L
        }
    }
}

4. The JS Implementation (jsMain)

// jsMain/src/jsMain/kotlin/StorageUtils.kt
import kotlinx.coroutines.await
import kotlin.js.Promise
// External declarations for navigator.storage
external interface StorageManager {
    fun estimate(): Promise<StorageEstimate>
}
external interface StorageEstimate {
    val quota: Number
    val usage: Number
}
external val navigator: dynamic
actual suspend fun getFreeDiskSpaceKb(path: String): Long {
    // JS ignores 'path' as it only maps to origin quota
    return try {
        if (navigator.storage != undefined) {
            val storageManager = navigator.storage.unsafeCast<StorageManager>()
            val estimate = storageManager.estimate().await()
            val quota = estimate.quota.toLong()
            val usage = estimate.usage.toLong()
            (quota - usage) / 1024L
        } else {
            -1L // Not supported in this browser environment
        }
    } catch (e: Exception) {
        -1L
    }
}

Validation and Performance Considerations: We integrated these calls into our pre-sync validation checks. By wrapping the JVM and Native calls in Dispatchers.IO (or using background workers in strict Native environments), we ensured the UI thread remained unblocked. Returning -1 provides a safe fallback mechanism, allowing the system to attempt the sync if capacity verification fails due to missing OS permissions.

What Are the Key Architectural Takeaways for KMP Developers?

When extending KMP beyond shared API calls and into hardware specifics, several best practices emerge:

• Design for Asynchronicity Early: Always consider JavaScript and WebAssembly limitations. If one platform requires async execution (like Web Storage APIs), force your commonMain interface to be a suspend function from the beginning.
• Understand the Native Memory Model: When using C-interop (like statvfs), always utilize memScoped to prevent memory leaks from unmanaged structs.
• Graceful Degradation is Mandatory: Hardware APIs can fail due to user permissions, OEM modifications, or unsupported browser modes. Always return a predictable fallback value (like -1) rather than throwing unhandled exceptions across the KMP bridge.
• Separate Path Logic from Domain Logic: Different OSes resolve paths differently. JS doesn’t use paths for storage estimation at all. Abstract path resolution before invoking your disk space utility.
• Prioritize Direct System APIs over Shell Commands: Using POSIX/Win32 APIs provides faster, safer, and more reliable metric gathering than executing native shell scripts.
• Align with Experienced Teams: Handling native OS abstractions requires deep platform knowledge. Companies looking to hire software developer resources should ensure their teams understand not just Kotlin, but the underlying C/POSIX, JVM, and browser execution environments.

How Should Teams Approach Platform-Specific API Limitations?

Building Kotlin Multiplatform applications forces teams to think critically about how disparate platforms handle identical business requirements. By leveraging the expect/actual paradigm thoughtfully—and embracing suspend functions to normalize blocking vs. asynchronous I/O—we successfully built a unified disk management utility. This prevented data corruption at the edge and ensured stable operations across JVM, Native Linux, and browser environments. For teams building complex, hardware-integrated edge systems, understanding these native bindings is a necessity. If your organization is facing similar architectural hurdles, contact us to explore how experienced engineering partners can accelerate your multiplatform delivery.

Social Hashtags

#Kotlin #KotlinMultiplatform #KMP #AndroidDev #ComposeMultiplatform #SoftwareEngineering #CrossPlatform #MobileDevelopment #JVM #Linux #JavaScript #EdgeComputing #Filesystem #DeveloperTips #Programming