android doze kills your background tasks and nobody explains why properly
been building a react native app that schedules stuff to run later. worked fine every time i tested it. shipped it, and it started missing schedules. only when the phone had been sitting idle for a while. never on my desk.
took me way too long to figure out what was going on so writing it up here.
what happens
you schedule something for 1am. check logs next morning:
01:00:00 alarm fired
01:00:02 connected (while back grounded, 2 seconds)
01:18:xx the actual send ran
the connection came up fine. in 2 seconds. while the phone was back grounded. but the code that was supposed to do something with that connection ran 18 minutes later when something else woke the phone up.
why
doze mode freezes javascript timers. setTimeout, setInterval, any polling loop on the js thread-all frozen. but native events (connection callbacks, lifecycle events, native module bridges) keep firing.
i had a setInterval checking "are we connected yet" every second. doze froze that loop. the connection came up, nobody noticed for 18 minutes because the thing checking for it was asleep.
the phone could do the work. my code just couldn't tell.
stuff i tried that didn't fix it
foreground service — keeps the process alive but doesn't unfreeze js timers. not the problem.
more setTimeout/setInterval variations, literally the thing causing it. spent two days making the problem worse.
HeadlessJS dropped in without changes compiled, never ran on newer RN. lost a few hours there.
the actual fix
move everything off timers. put your work directly in the event handler.
instead of polling to check if you're connected:
js// this is frozen by doze. don't.
setInterval(() => { if (isReady()) doWork() }, 1000)
do this:
jsconnection.on('status', (state) => {
if (state === 'connected') {
doWork(job)
}
})
native events survive doze. timers don't. that's the whole thing.
for waking up at the right time — native AlarmManager with setExactAndAllowWhileIdle. it's the doze-piercing variant. set that to fire at your scheduled time, let it cold-start the app, then your event handler picks it up.
AlarmManager fires at T (native, survives doze)
→ app cold starts
→ opens connection
→ "connected" event fires
→ do the work in the handler
no timers anywhere in that chain.
persistence matters
your app is probably a cold start at fire time. process got killed hours ago. anything in memory is gone. write your pending jobs to AsyncStorage (or whatever persistent store you use) when scheduling, read them back on every launch. if the job isn't on disk it doesn't exist.
delete after success, not before if something crashes mid-run the job stays on disk for next time instead of disappearing silently.
const job = await Storage.get('pending_job')
if (job) reconnect()
connection.on('status', (state) => {
if (state === 'connected') {
doWork(job)
Storage.delete('pending_job')
}
})
samsung/xiaomi/oppo will still kill you
stock android respects the alarm. samsung and the rest have their own battery killing layer on top. your alarm fires, your receiver triggers, and then the OS kills your service before the js task starts. nothing you can do except prompt the user to whitelist your app from battery optimisation on those devices. fun times.
wrapping up
i'm cleaning up the native alarm + headless task + event-driven scaffolding into a starter repo so other people don't have to wire this from scratch. if that sounds useful drop a comment.
**
