APK Downloader
·12 min read

Sideloaded APK Won't Become the Default Browser, Dialer or Launcher: RoleManager and Default App Roles, Diagnosed Step by Step

You installed a third-party browser but it never appears in the Default apps list; or you set it as default and https links still open the system browser. A sideloaded dialer, launcher or SMS app cannot be made default either. These are rarely broken apps - since Android 10, RoleManager decides eligibility (qualification) for each role: manifest declarations, intent-filters, the BROWSABLE category, HTTPS scheme, App Links verification, exported components, and OEM overrides all interact. A role mechanism table, runnable adb / cmd role / curl commands, a nine-step diagnostic path, a status reference, an FAQ, and verified internal links.

default appsRoleManagerintent-filteradbtroubleshooting

There is a class of problem that makes people assume they downloaded a crippled build. A third-party browser installs, opens, browses and saves bookmarks - yet in Settings -> Apps -> Default apps -> Browser, it is simply not in the list. Or you manage to set it as default and tapping an https:// link still hands you to the system browser. Sideloaded dialers, launchers and SMS apps hit the same wall.

So people reinstall, clear defaults, switch versions, hunt for an "unlocked default" build. Almost none of that touches the cause. If the app runs, installation succeeded. If it cannot be made default, it did not pass the system's eligibility check for that role.

The key distinction: since Android 10 (API 29), "default app" is no longer an arbitrary toggle - it is a set of roles managed by RoleManager. The system only lists apps that satisfy *all* qualification conditions for a role. A sideloaded APK missing one category, one scheme, or a correct android:exported declaration will never appear in that list, no matter how many times you reinstall it.

This article takes that eligibility pipeline apart, gives you a command to verify each stage, and ends with the cases that are ROM-specific or missing from the app manifest and therefore not fixable from the device.

1. Distinguish four kinds of "can't set default"

SymptomMost likely layerHow it differsFirst check
App absent from the Default apps listRole qualification not metApp runs normallycmd role holders + manifest declarations
Listed and selected, but links still go elsewhereApp Links verification / stale preferredSelection works, behavior does notpm get-app-links, resolve-activity
Default set, then reverts after reboot or updateRole reset / replaced by updateUsed to workCompare role holders before/after
Dialer / SMS / launcher cannot be setRole-specific qualificationsBrowser works, these do notCorresponding intent-filter declarations

If the app itself will not install or crashes on launch, that is out of scope - see APK install failed troubleshooting and launch crash logcat guide. This article covers "installs, runs fine, just cannot be default".

2. Mechanism table: what RoleManager evaluates

CheckWhat it inspectsSymptom when unmetDecided by
Role existsandroid.app.role.BROWSER / DIALER / SMS / HOME etc.No such role on this ROMOS version / ROM
Manifest intent-filterRequired action + category + dataNot in the candidate listAPK AndroidManifest
BROWSABLE categoryRequired for the browser roleMissing from browser listAPK manifest
HTTPS / HTTP schemeBrowser role must handle https (usually http too)Some links do not routeAPK manifest
android:exportedAndroid 12+ (targetSdk 31) requires explicit declaration; intent-filter components need trueComponent not externally callableAPK manifest
App enabled statePackage must not be disabled, and must be installed for this userMissing from the listPackage state / multi-user
App Links verificationAndroid 12+ has separate verification for "open links directly"Default set, links still open in browserDomain assetlinks.json
OEM overrideMIUI / HyperOS / ColorOS ship their own "Default apps" screenadb says set, UI disagreesVendor customization

Key points:

  • A role is two-stage: eligibility + holder. The system first computes which apps *qualify*, then a user or default logic designates the *holder*. cmd role holders only shows the current holder, not the eligible set - so you must pair it with query-activities to answer "can this package handle the intent at all".
  • The most commonly missing declaration in sideloaded browsers is `BROWSABLE`. Many APKs that only open web pages in-app declare android.intent.action.VIEW and the https scheme but omit android.intent.category.BROWSABLE; they can open a link themselves yet never enter the system browser candidates.
  • "Being the default" and "opening links directly" are two different things. The first is role ownership; the second additionally requires App Links domain verification (especially visible since Android 12). That is the pipeline covered in links still open in the browser after sideloading. They frequently co-occur but have different objects of investigation.

3. Per-role qualification quick reference

Role constantMeaningRequired action / category / dataCommon sideload gap
android.app.role.BROWSERDefault browserVIEW + BROWSABLE + DEFAULT + http/https schemeMissing BROWSABLE or https
android.app.role.DIALERDefault dialerDIAL (and CALL) + tel schemeOnly declares VIEW tel
android.app.role.SMSDefault SMSSMS_DELIVER / WAP_PUSH_DELIVER + related permissionsMissing receiver declarations
android.app.role.HOMEDefault launcherMAIN + HOME + DEFAULT (or LAUNCHER)Built as an ordinary app
android.app.role.CALL_REDIRECTIONCall redirectionMatching service + bind permissionMissing service declaration
android.app.role.GALLERY / MUSICGallery / musicMatching VIEW + MIME typesHeavily vendor-customized

Knowing the exact role name is what makes the commands work. For why targetSdk forces the android:exported requirement, see targetSdkVersion explained.

4. Runnable command list

All commands need adb and USB debugging. Replace com.example.app with the target package. Every command is read-only or only adjusts role settings - nothing wipes data.

# 1) Roles the system supports, and their current holders
adb shell cmd role
adb shell cmd role holders android.app.role.BROWSER
adb shell cmd role holders android.app.role.DIALER
adb shell cmd role holders android.app.role.SMS
adb shell cmd role holders android.app.role.HOME
adb shell dumpsys role | head -100

# 2) Reverse-check: can this package handle the intent a browser must handle? (the decisive cut)
adb shell cmd package query-activities --brief -a android.intent.action.VIEW -d https://www.example.com
adb shell cmd package resolve-activity --brief -a android.intent.action.VIEW -d https://www.example.com
adb shell cmd package resolve-activity --brief -a android.intent.action.DIAL -d tel:10086
adb shell cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME

# 3) Dump manifest clues from the installed package (BROWSABLE / exported / scheme)
adb shell cmd package dump com.example.app | grep -iE 'BROWSABLE|android.intent.action.VIEW|android.intent.action.DIAL|scheme|exported|HOME'
aapt dump badging app.apk | grep -iE 'package:|sdkVersion:|targetSdkVersion:|launchable-activity'
adb shell dumpsys package com.example.app | grep -iE 'disabled|enabled|userId|targetSdk'

# 4) Confirm package state: disabled? installed only for another user?
adb shell pm list packages -d | grep example
adb shell pm list users
adb shell pm list packages --user 0 | grep example

# 5) Verify the App Links domain (a separate pipeline from "being default")
adb shell pm get-app-links com.example.app
adb shell pm verify-app-links --re-verify com.example.app
curl -sI --max-time 10 https://www.example.com/.well-known/assetlinks.json

# 6) Live test: fire a VIEW intent and see who actually takes it
adb shell am start -a android.intent.action.VIEW -d https://www.example.com
adb logcat -c && adb logcat -v brief | grep -iE 'RoleManager|role|ResolverActivity|ActivityTaskManager|START'

# 7) Debug-only: temporarily bypass qualification / set the holder manually (own device only; may reset)
adb shell cmd role set-bypassing-role-qualification true
adb shell cmd role add-role-holder android.app.role.BROWSER com.example.app 0
adb shell cmd role remove-role-holder android.app.role.BROWSER com.example.app 0

Three things to look for in the output:

  1. If query-activities --brief does not list the target package, it never declared that it can handle the intent - the most common reason for "not in the list". That is a missing manifest declaration; reinstalling changes nothing.
  2. cmd role holders prints the current holder. If it shows the system browser, your setting did not land on the AOSP role; if the ROM has its own "Default apps" page, the two can be out of sync.
  3. pm get-app-links prints a verification:... state. If it is legacy_failure / none, tapping links on *the app's own domain* may still be blocked even with the browser role set - coordinate this with App Links troubleshooting.

For the full assetlinks.json and signing-certificate-fingerprint investigation, see App Links verification troubleshooting. For links blocked by server-side 403/404, see download link 403/404 troubleshooting.

5. Nine-step diagnostic path

Step 1 - Confirm the app works. Open it manually and visit an https site. Works -> role investigation. Does not -> start with blank in-app WebView or connectivity.

Step 2 - Confirm the role name and OS support. cmd role lists available roles. Debloated ROMs and Android TV devices may not ship the full role set, so the Settings entry simply does not exist.

Step 3 - Verify qualification with `query-activities`. This is the decisive cut. If the package appears in the result, it is eligible for the candidate list; if not, it is a missing manifest declaration - skip to step 9.

Step 4 - Check the three manifest essentials. BROWSABLE category, https scheme, android:exported=true. Cross-check with aapt dump badging (local APK) and cmd package dump (installed package).

Step 5 - Check package state and user. pm list packages -d for disabled; pm list users plus pm list packages --user 0 to confirm it is installed for the current user. If it exists only in a Work Profile, the main space's Default apps list cannot show it - see Work Profile / multi-user install troubleshooting.

Step 6 - Check App Links verification state. pm get-app-links. This decides whether "open links directly" can hold, independently of role ownership.

Step 7 - Test intent routing live. am start -a VIEW -d https://... while watching logcat for ResolverActivity and START. An "Open with" chooser means the system sees multiple candidates and no settled default; jumping straight to the system browser means it is still the role holder.

Step 8 - Separate the AOSP role from the OEM override. MIUI / HyperOS / ColorOS have their own "Default apps" screen that may override cmd role. Check both, set both to the same app, then re-test.

Step 9 - Accept the "unfixable" cases. If step 3 confirms missing qualification (no BROWSABLE, no exported, or installed only for another user), it is an APK or installation-method issue - Settings cannot fill it in. Get the latest official build, or read APK manifest structure explained to understand the declaration difference.

6. Status / error reference

Keyword / statusMeaningLayerUser-fixable?
query-activities returns nothingNo matching intent-filter declaredAPK manifestNo (change build)
Error: package does not qualify for the roleRole qualification unmetRoleManagerNo
holders: shows another packageCurrent holder is not the targetRole settingYes (re-select default)
pm get-app-links -> legacy_failureDomain verification failedApp LinksPartly (server assetlinks)
verification: noneVerification never ranApp LinksYes (verify-app-links --re-verify)
"Open with" chooser appearsNo unique default / conflicting preferredResolverYes (choose "Always")
android:exported install/invoke failuretargetSdk 31+ without explicit declarationAPK manifestNo
ROM setting disagrees with cmd roleVendor overrideCustomization layerPartly (align both)

7. Version differences

Android versionDefault-app-related change
Before 8.0 (API 26)Implicit PreferredActivity / "open by default" records, loosely defined
10 (API 29)RoleManager introduced; BROWSER / DIALER / SMS / HOME become formal roles
12 (API 31)App Links verification tightened; intent-filter components must declare android:exported explicitly
12L / 13Per-app user toggle for "open supported links"; failed verification means no auto-open
14-16Tighter install/background rules for low-targetSdk apps, indirectly affecting role availability

If the main symptom is "links still open in the browser" rather than "cannot select in the list", make App Links verification troubleshooting your primary path. If it is "installed but no icon at all", see installed but no app icon.

8. FAQ

Q1: My third-party browser is completely absent from Default apps - was the package modified?

Usually not. The most common cause is a manifest missing BROWSABLE or the https scheme, so it fails BROWSER role qualification. query-activities --brief settles it; re-signing is unrelated to this check.

Q2: Will forcing it with `cmd role add-role-holder` solve it permanently?

Not guaranteed. Bypassing qualification (set-bypassing-role-qualification) is a development/debugging aid; an OS upgrade, app update or reboot may reset it, and OEM settings may ignore it. It is not a long-term user solution.

Q3: I set the default browser, so why do some links still open the system browser?

Because "role holder" and "App Links domain verification" are separate pipelines. If that link's domain verifies as legacy_failure, the system may not hand it to your app. Check pm get-app-links and follow the App Links path.

Q4: Does `android:exported` really have to be declared?

With targetSdk >= 31, any component carrying an intent-filter must declare android:exported explicitly, or installation fails / the component is not externally callable. That is manifest-level; users cannot change it - use a compliant newer build.

Q5: Can an app installed in a Work Profile become the main space's default?

No. Role holders are per user as well; the main space's Default apps list only shows packages installed and qualified for that user. See Work Profile / multi-user install troubleshooting.

Q6: Does clearing defaults / resetting app preferences help?

It helps when a stale preferred activity overrides a default you once set. It does nothing when qualification is unmet and the app is not listed. Use step 3 to decide which case you are in.

Q7: I set a sideloaded launcher as HOME and now the screen is black. What now?

The launcher starts but fails to render. Confirm the holder with adb shell cmd role holders android.app.role.HOME, then trigger the chooser with adb shell am start -a android.intent.action.MAIN -c android.intent.category.HOME, or switch back temporarily.

Q8: What if `cmd role` does not exist or errors out?

Some older devices (Android 9 and below) or debloated ROMs lack the service. Default apps then use the legacy PreferredActivity mechanism - investigate with dumpsys package | grep -i preferred and the Settings UI.

Q9: Why can a store-installed equivalent be set as default while the sideloaded one cannot?

Version differences (newer builds added the declaration), an incomplete split-APK install, or a stripped channel build. Compare the two with aapt dump badging to locate the gap.

Q10: How do I quickly decide between "role" and "App Links"?

By symptom: cannot select / absent from the list -> role qualification (this article). Can select, but links do not route -> App Links verification. Running both checks is harmless; all the commands are read-only.

9. Further reading

Bottom line

"Installs, runs, cannot be default" almost always comes down to RoleManager's qualification decision, not a broken APK. Two checks do the work: `cmd package query-activities --brief` to see whether the package can handle the role's intent, and `cmd role holders` to see who currently holds it. If the first fails, it is a missing manifest declaration (change build); if the second is wrong, the setting did not land on the AOSP role (re-select, and watch for OEM overrides). Remember that "being the default" and "opening links directly" are separate pipelines, and you will stop mistaking a role problem for an App Links problem.