Stuck Wake Locks

Partial wake locks are a mechanism in the PowerManager API that lets developers keep the CPU running after a device's display turns off (whether due to system timeout or the user pressing the power button). Your app acquires a partial wake lock by calling acquire() with the PARTIAL_WAKE_LOCK flag. A partial wake lock becomes stuck if it is held for a long time while your app is running in the background (no part of your app is visible to the user). This condition drains the device's battery because it prevents the device from entering lower power states. Partial wake locks should be used only when necessary and released as soon as no longer needed.

To help you improve app quality, Android automatically monitors apps for stuck partial wake locks and displays the information in Android Vitals. For information on how the data is collected, see Play Console docs.

If your app has a stuck partial wake lock, you can use the guidance in this page to diagnose and fix the problem.

Fix the problem

Wake locks were introduced in early versions of the Android platform, but over time, many use cases that previously required wake locks are now better served by newer features like JobScheduler and Firebase JobDispatcher. This section contains tips for fixing your wake locks, but in the long term, consider migrating your app to follow the recommendations in the best practices section.

Identify and fix places in your code that acquire a wake lock, such as newWakeLock(int, String) or WakefulBroadcastReceiver. Here are some tips:

• We recommend including your package, class, or method name in the wake lock tag name so that you can easily identify the location in your source where the wake lock was created. Here are some additional tips:

  • Leave out any personally identifying information (PII) in the name, such as an email address. Otherwise, the device logs _UNKNOWN instead of the wake lock name.
  • Don't get the class or method name programmatically, for example by calling getName(), because it could get obfuscated by Proguard. Instead use a hard-coded string.
  • Don't add a counter or unique identifiers to wake lock tags. The system will not be able to aggregate wake locks created by in same method because they all have unique identifiers.

• Make sure your code releases all the wake locks that it acquires. This is more complicated than making sure that every call to acquire() has a corresponding call to release(). Here's an example of a wake lock that is not released due to an uncaught exception:

  void doSomethingAndRelease() throws MyException {
      mWakeLock.acquire();
      doSomethingThatThrows();
      mWakeLock.release();  // does not run if an exception is thrown
  }
  

  Here's a correct version of the code:

  void doSomethingAndRelease() throws MyException {
      try {
          mWakeLock.acquire();
          doSomethingThatThrows();
      } finally {
          mWakeLock.release();
      }
  }
  

• Make sure that wake locks are released as soon as they are no longer needed. For example, if you are using a wake lock to allow a background task to finish, make sure that release happens when that task finishes. If a wake lock is held longer than expected without being released, this could mean that your background task is taking more time than expected.

After fixing the problem in code, verify that your app correctly releases wake locks by using the following Android tools:

• dumpsys - a tool that provides information about the status of system services on a device. To see the status of the power service, which includes a list of wake locks, run adb shell dumpsys power.

• Battery Historian - a tool that parses the output of an Android bug report into a visual representation of power related events.

Best Practices

In general, your app should avoid partial wake locks because it is too easy to drain the user's battery. Android provides alternative APIs for almost every use-case that previously required a partial wake lock. One remaining use-case for partial wake locks is to ensure that a music app continues to play when the screen is off. If you are using wake locks to run tasks, consider the following alternatives:

• If your app is performing long-running HTTP downloads, consider using DownloadManager.
• If your app is synchronizing data from an external server, consider creating a sync adapter.
• If your app needs to execute background tasks at regular intervals, consider using JobScheduler or Firebase JobDispatcher. For information on triggering tasks at specific intervals, see Intelligent Job-Scheduling.

The benefit to using those APIs is that the system intelligently batches and/or defers those tasks based on the power-state of the device.

If you must use partial wake locks, follow these recommendations:

• Make sure some portion of your app remains in the foreground. For example, if you need to run a service, start a foreground service instead. This visually indicates to the user that your app is still running.
• Make sure the logic for acquiring and releasing wake locks is as simple as possible. When your wake lock logic is tied to complex state machines, timeouts, executor pools, and/or callback events, any subtle bug in that logic can cause the wake lock to be held longer than expected. These bugs are difficult to diagnose and debug.