How to Inspect Incremental Installations and Virtual Filesystem Blocks on Android Using ADB dumpsys incremental

Modern Android operating systems (Android 11 and later) feature the Incremental File System (incfs), a specialised Linux virtual filesystem designed to accelerate large application and game installations. With Incremental installation, Android allows an app to launch and execute before its entire APK package—often gigabytes in size—has finished downloading or sideloading. Android streams essential code blocks first while background threads fetch the remaining assets on demand.

When developing, testing, or troubleshooting large game packages and streaming installations, developers often encounter frozen activities, missing asset crashes, or read stalls. The Android Debug Bridge (ADB) service command dumpsys incremental exposes low-level virtual filesystem metrics, active mount points, pending block requests, read error counts, and storage binding health.

How Incremental Installation and incfs Function

Traditional APK installation requires the entire binary file to be written and verified before the Android Package Manager (PackageManagerService) can install and execute the app. In contrast, incfs acts as a read-only virtual filesystem mount:

• The APK is split into 4 KB data blocks.
• The installer populates metadata, signatures, and essential execution blocks required for app launch.
• When the app requests an unpopulated file block during runtime, incfs intercepts the page fault and requests the block from the streaming source daemon or local data loader.
• If the data loader fails to supply the block within a kernel timeout threshold, the read operation stalls or raises an I/O exception.

Connecting to ADB and Verifying incfs Kernel Support

Connect the Android device or emulator to the development workstation with USB debugging enabled. Verify the ADB connection:

adb devices

Check if the device kernel supports incfs by inspecting the system features exposed through package manager:

adb shell pm has-feature android.software.incremental_delivery

If the command returns true, the kernel supports Incremental File System mounts and background streaming installations.

Inspecting Active Mounts with dumpsys incremental

To inspect the high-level state of all Incremental mounts and active streaming sessions, run:

adb shell dumpsys incremental

The output presents details across several diagnostic sections:

*** Incremental Service ***
Mounts: 1
  StorageId: 1
    MountPath: /data/incremental/MT_1/mount
    BindPath: /data/app/~~u-h2K_8vM==/com.example.game-1
    DataLoader: com.android.incremental.DataLoaderService
    Status: Healthy
    TotalBlocks: 524288 (2048 MB)
    LoadedBlocks: 131072 (512 MB, 25.0%)
    MissingBlocks: 393216 (1536 MB)

Key metrics revealed by this inspection include:

• StorageId: Unique identifier assigned to the virtual storage instance.
• MountPath & BindPath: The physical backing directory and the target application directory where the virtual filesystem is bound.
• LoadedBlocks vs MissingBlocks: The exact proportion of 4 KB pages currently persisted on storage versus pages still pending background delivery.
• Status: Reflects the operational health of the DataLoader pipe.

Diagnosing Read Stalls and Missing Page Requests

When an incrementally loaded application freezes or crashes with an ANR (Application Not Responding), it often indicates that the main thread performed a synchronous read against a block that has not yet been streamed. To view detailed block read statistics, append the --stats flag:

adb shell dumpsys incremental --stats

Inspect the output for the following critical indicators:

Metric	Meaning	Troubleshooting Action
ReadsFailed	Number of block read attempts that returned kernel I/O errors	Verify source package signature integrity and storage free space
ReadsDelayed	Block read requests that waited on the DataLoader queue	Optimise asset streaming priority in the application build configuration
ReadsTimedOut	Requests where the block wait exceeded kernel timeout thresholds	Check network stability between client and streaming server
PendingReads	Current backlog of pending block read operations	Investigate high disk I/O contention or thread blocking

Testing Incremental Installation Behaviour via ADB

Developers can test how an application responds to progressive block loading using the --incremental flag during APK installation:

adb install --incremental LargeGameBuild.apk

ADB establishes an incremental streaming pipeline and launches the application immediately once critical blocks are transferred. While the application runs, repeatedly monitor the block ingestion rate:

adb shell dumpsys incremental | grep -E "LoadedBlocks|MissingBlocks|Status"

To simulate DataLoader disconnection and observe how the app handles missing blocks, pause or terminate the streaming transfer process. The journal will record DataLoader disconnection and identify blocked system calls:

adb logcat -s incfs:* IncrementalService:*

By regularly inspecting dumpsys incremental during staging, Android development teams ensure that critical launch sequences, splash screens, and initial levels load smoothly without triggering kernel read timeouts.