How to Inspect Runtime Resource Overlays and Theme Packages on Android Using ADB dumpsys overlay

Modern Android device customisation—including dynamic wallpaper-based theming (Material You / Monet), OEM vendor skins (Samsung One UI, Xiaomi HyperOS, Google Pixel themes), custom system accent colours, icon shape masks, and carrier-branded system fonts—is powered under the hood by Runtime Resource Overlays (RRO). Rather than modifying compiled system APK files or recompiling the framework, Android’s resource management architecture allows overlay APK packages to intercept and dynamically substitute values, layouts, strings, and drawables in target applications at runtime.

The Android operating system coordinates these overlays through the OverlayManagerService (OMS). When custom themes fail to apply, system UI elements glitch after an OTA system update, or enterprise administrators diagnose unwanted third-party package modifications, the Android Debug Bridge (ADB) command dumpsys overlay exposes the complete registry of installed, enabled, and prioritized overlay packages. This guide explains how the Android RRO subsystem functions and details how to extract, audit, and manipulate overlay configurations using ADB.

Architecture of Android Runtime Resource Overlays (RRO)

The Android resource overlay framework consists of three foundational layers:

• Target Package: The base application whose resources are being modified (e.g. android for the core framework, com.android.systemui for system icons and notification panels, or com.android.settings for preferences).
• Overlay Package: An APK containing replacement resources (defined in XML) and a manifest referencing the target package via the <overlay android:targetPackage="..."> declaration. Overlays do not execute independent application code; they only provide alternative compiled assets.
• OverlayManagerService (OMS): The system service within system_server that tracks overlay states (enabled, disabled, missing target), calculates loading priority orders, and instructs the native AssetManager (libandroid_runtime) to link overlay resource tables on process creation.
• Overlay Categories and Fabric Overlays: Android groups overlays into functional categories (such as android.theme.customization.accent_color, android.theme.customization.font, or android.theme.customization.icon_pack). When a user selects a new accent colour in system settings, OMS enables the matching overlay and disables conflicting alternatives.

Using ADB diagnostics, developers can monitor whether custom system styles or enterprise branding profiles are accurately applied to target applications.

Verifying ADB Connectivity and Overlay Service Status

Connect your Android test device or emulator via USB or wireless debugging and verify detection:

adb devices -l

Next, confirm that the overlay service is registered in the Android Binder service directory:

adb shell service list | grep -i overlay

The output returns the registered Binder interface:

184	overlay: [android.content.om.IOverlayManager]

If present, the Overlay Manager Service is fully operational and accessible for command-line diagnostics.

Dumping Global Overlay Service State

To inspect the complete registry of all installed overlays across all target packages, execute the primary dumpsys command:

adb shell dumpsys overlay

The output displays a structured list organized by target package name and multi-user profile:

User 0:
  com.android.systemui:
    [x] com.google.android.theme.icon_pack.filled.systemui (priority 10, category: android.theme.customization.icon_pack)
    [ ] com.google.android.theme.icon_pack.rounded.systemui (priority 10, category: android.theme.customization.icon_pack)
  android:
    [x] com.google.android.theme.color.charcoal (priority 5, category: android.theme.customization.accent_color)
    [ ] com.google.android.theme.color.emerald (priority 5, category: android.theme.customization.accent_color)
    [x] com.android.internal.systemui.navbar.gestural (priority 1, category: null)
    [ ] com.android.internal.systemui.navbar.threebutton (priority 1, category: null)

Key indicators in this output include:

• [x] Enabled Flag: Indicates that the overlay package is actively loaded by the target’s AssetManager.
• [ ] Disabled Flag: The overlay package is installed on the system partition or data drive but currently inactive.
• Priority: When multiple overlays modify the same resource ID (e.g. @color/accent_device_default), higher-priority overlays override lower-priority packages.
• Category: Groups related mutually-exclusive overlays (e.g. system font styles or gesture navigation bars).

Filtering Overlays for Specific Target Packages

Modern Android operating systems contain hundreds of vendor overlays. To focus on overlays modifying a specific target package—such as core Android framework resources—filter dumpsys output using grep or cmd overlay:

# Filter dumpsys for framework overlays
adb shell dumpsys overlay | grep -A 15 "android:"

# Alternative: list overlays specifically targeting System UI
adb shell cmd overlay list com.android.systemui

The cmd overlay list output clearly marks active states:

com.android.systemui
    [x] com.android.theme.icon_pack.filled.systemui
    --- com.android.theme.icon_pack.circular.systemui
    --- com.android.theme.icon_pack.rounded.systemui

(Where [x] signifies an enabled overlay and --- signifies a disabled overlay).

Enabling and Disabling Overlays via ADB

Android provides administrative control over runtime overlays via the cmd overlay command-line interface, allowing developers to test theme switches and UI scaling without manual navigation through device settings.

Enabling an Overlay Package

To enable a specific overlay package (such as switching to a circular system icon pack):

# Syntax: cmd overlay enable [--user <USER_ID>] <PACKAGE_NAME>
adb shell cmd overlay enable com.android.theme.icon_pack.circular.systemui

The system server immediately signals the target process (com.android.systemui) to reload its asset tables, updating status bar icons, battery meters, and Wi-Fi symbols without requiring a device reboot.

Disabling an Overlay Package

To disable an active overlay and revert to default system resources:

adb shell cmd overlay disable com.android.theme.icon_pack.circular.systemui

Adjusting Overlay Priority Order

If two custom enterprise branding overlays define competing values for the same corporate colour scheme, you can adjust their loading hierarchy using set-priority:

# Elevate priority of a custom branding overlay above default vendor styles
adb shell cmd overlay set-priority com.example.custom.theme.accent highest

Troubleshooting Common Overlay Failures

When custom themes fail to render or system apps crash upon theme switching, check for these common configuration issues:

• Missing Target Package (STATE_TARGET_IS_MISSING): If an overlay APK is installed for an application that was uninstalled or disabled via package manager, the overlay enters an orphaned error state. Inspect detailed package statuses using:

  adb shell cmd overlay dump com.example.custom.overlay

• Signature and Permission Mismatches: Unprivileged third-party apps cannot install runtime overlays modifying system framework resources unless the overlay is pre-installed in /system/overlay/, signed with the platform certificate, or authorized via Fabric Overlay policies. Non-platform overlays will be rejected with SECURITY_EXCEPTION in logcat.
• Resource ID Drift Across OS Upgrades: If an overlay targets a dynamic resource ID that changed between major Android versions (e.g. upgrading from Android 13 to Android 14), the AssetManager will fail to link resources, causing layout distortion. Check logcat for resource resolution warnings:

  adb logcat -d -s OverlayManager:V AssetManager:W