Android 14 VPN Fix: Migrate to specialUse Services

Zusammenfassung

Pixel shares a practical Android 14 migration guide for VPN apps using foreground services. It explains why systemExempted can trigger a SecurityException and service failure, and outlines the working path: specialUse, FOREGROUND_SERVICE_SPECIAL_USE permission, and a vpn subtype in the manifest.

DEV Community

Android 14 foreground services: the specialUse migration that saved our VPN

TL;DR — On Android 14 a regular app cannot start a foreground service with systemExempted: startForeground() throws SecurityException, the service silently dies, and the user just sees "VPN is not working". For a VPN client that isn't a system app, the working path is specialUse + FOREGROUND_SERVICE_SPECIAL_USE + a vpn subtype in the manifest. Context I maintain an Android VPN client built on VpnService. Since API 26 it runs as a foreground service: persistent notification, startForegroundService(), startForeground() inside the service. That worked fine on Android 8–13. Android 14 (API 34) tightened the rules: every foreground service must declare a type, and the type must be allowed for the app. Depending on what exactly the system considers violated, you get MissingForegroundServiceTypeException or SecurityException. For a VPN, FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED looked logical: val fgsType = if (Build.VERSION.SDK_INT >= 34) {
ServiceInfo.FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
} else 0

startForeground(NOTIF_VPN_ID, notif, fgsType)
It works constantly like an antivirus or a system daemon, so "system exempted" seemed right. The manifest got android:foregroundServiceType="systemExempted". On Android 12 this worked perfectly — the type wasn't enforced that strictly. On Android 14 it did not. Symptoms On an API 34 emulator the app started, showed "Connecting…", and a few seconds later dropped into an error state. Logcat and the service's own log looked like this: E/AppVpnService: startForeground failed: SecurityException: ...
I/AppVpnService: SVC_FATAL reason=foreground_fail
I/AppVpnService: SVC_STOP reason=exhausted last=foreground_fail
startForeground() threw SecurityException, the service never got the foreground flag, retries were exhausted (the app has a 3-attempt limit), and the user saw "Disconnected (error)". The important detail: the app did not crash. The exception was caught, the UI kept working — but the VPN did not. This kind of bug is easy to miss if you only check "does the app crash?". The exact message varies between versions, but the root cause is the same: systemExempted requires android.permission.FOREGROUND_SERVICE_SYSTEM_EXEMPTED, which has signature|privileged protection level — a regular app can't get it at all. Why Android 12 didn't reproduce it Before Android 14 the FGS type was only needed for some permissions and wasn't enforced that hard. On Android 12 (API 31) the old code worked, so the bug only appeared on an API 34 emulator. Lesson: don't test foreground services only on older APIs. Another emulator surprise: after fixing FGS the native tunnel still didn't come up — the app is arm64-only and the x86 emulator uses ARM translation. So SVC_FOREGROUND ok is a real win, but "full VPN on emulator" is not a valid test. You need a real arm64 device. That's a separate story. What actually needs to change 1. Manifest




Key elements: android:foregroundServiceType="specialUse" — the type; FOREGROUND_SERVICE_SPECIAL_USE — a normal (not runtime) permission; — the subtype that explains why. Google Play reviewers read it when the app is published there. 2. Code return try {
val fgsType = if (Build.VERSION.SDK_INT >= 34) {
ServiceInfo.FOREGROUND_SERVICE_TYPE_SPECIAL_USE
} else 0

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && fgsType != 0) {
    startForeground(NOTIF_VPN_ID, notif, fgsType)
} else {
    startForeground(NOTIF_VPN_ID,...

Android 14 VPN Fix: Migrate to specialUse Services
Powered by Readybot.io

Das Neueste von Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …