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.
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"
| Symptom | Most likely layer | How it differs | First check |
|---|---|---|---|
| App absent from the Default apps list | Role qualification not met | App runs normally | cmd role holders + manifest declarations |
| Listed and selected, but links still go elsewhere | App Links verification / stale preferred | Selection works, behavior does not | pm get-app-links, resolve-activity |
| Default set, then reverts after reboot or update | Role reset / replaced by update | Used to work | Compare role holders before/after |
| Dialer / SMS / launcher cannot be set | Role-specific qualifications | Browser works, these do not | Corresponding 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
| Check | What it inspects | Symptom when unmet | Decided by |
|---|---|---|---|
| Role exists | android.app.role.BROWSER / DIALER / SMS / HOME etc. | No such role on this ROM | OS version / ROM |
| Manifest intent-filter | Required action + category + data | Not in the candidate list | APK AndroidManifest |
| BROWSABLE category | Required for the browser role | Missing from browser list | APK manifest |
| HTTPS / HTTP scheme | Browser role must handle https (usually http too) | Some links do not route | APK manifest |
android:exported | Android 12+ (targetSdk 31) requires explicit declaration; intent-filter components need true | Component not externally callable | APK manifest |
| App enabled state | Package must not be disabled, and must be installed for this user | Missing from the list | Package state / multi-user |
| App Links verification | Android 12+ has separate verification for "open links directly" | Default set, links still open in browser | Domain assetlinks.json |
| OEM override | MIUI / HyperOS / ColorOS ship their own "Default apps" screen | adb says set, UI disagrees | Vendor 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 holdersonly shows the current holder, not the eligible set - so you must pair it withquery-activitiesto 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.VIEWand thehttpsscheme but omitandroid.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 constant | Meaning | Required action / category / data | Common sideload gap |
|---|---|---|---|
android.app.role.BROWSER | Default browser | VIEW + BROWSABLE + DEFAULT + http/https scheme | Missing BROWSABLE or https |
android.app.role.DIALER | Default dialer | DIAL (and CALL) + tel scheme | Only declares VIEW tel |
android.app.role.SMS | Default SMS | SMS_DELIVER / WAP_PUSH_DELIVER + related permissions | Missing receiver declarations |
android.app.role.HOME | Default launcher | MAIN + HOME + DEFAULT (or LAUNCHER) | Built as an ordinary app |
android.app.role.CALL_REDIRECTION | Call redirection | Matching service + bind permission | Missing service declaration |
android.app.role.GALLERY / MUSIC | Gallery / music | Matching VIEW + MIME types | Heavily 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 0Three things to look for in the output:
- If
query-activities --briefdoes 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. cmd role holdersprints 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.pm get-app-linksprints averification:...state. If it islegacy_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 / status | Meaning | Layer | User-fixable? |
|---|---|---|---|
query-activities returns nothing | No matching intent-filter declared | APK manifest | No (change build) |
Error: package does not qualify for the role | Role qualification unmet | RoleManager | No |
holders: shows another package | Current holder is not the target | Role setting | Yes (re-select default) |
pm get-app-links -> legacy_failure | Domain verification failed | App Links | Partly (server assetlinks) |
verification: none | Verification never ran | App Links | Yes (verify-app-links --re-verify) |
| "Open with" chooser appears | No unique default / conflicting preferred | Resolver | Yes (choose "Always") |
android:exported install/invoke failure | targetSdk 31+ without explicit declaration | APK manifest | No |
ROM setting disagrees with cmd role | Vendor override | Customization layer | Partly (align both) |
7. Version differences
| Android version | Default-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 / 13 | Per-app user toggle for "open supported links"; failed verification means no auto-open |
| 14-16 | Tighter 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
- Links still open in the browser after sideloading: domain verification and assetlinks.json
- Work Profile / multi-user install troubleshooting: per-user installs and roles
- Blank in-app WebView after sideloading: cleartext and WebView layer
- targetSdkVersion explained: origin of the exported requirement
- Anatomy of an APK file: what the manifest contains
- APK install failed troubleshooting: prerequisites before any of this
- App crashes on launch: logcat guide: crashes after being set default
- Installed but no app icon: launcher-related symptoms
- how to verify APK signature before installing: signature conflicts when switching builds
- safe APK download & install guide: the full flow from download to verification
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.