Your Widget Extension Can Submit a BGTaskScheduler Request. It Just Cannot Register the Handler

Moving refresh ownership back to the host app

Once I accepted the dead end, I rewrote the design around a different subject. The host app owns the refresh. The widget goes back to being the thing that reads a result and draws it.

The app takes on three jobs in order: register at launch, pick the next image and write it into the App Group when it wakes, then ask WidgetCenter to reload once the write has landed.

// AppDelegate.swift — the host app; register can only happen here
import BackgroundTasks
import WidgetKit
 
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
 
    // Must happen before launch finishes. Register late and registration itself fails.
    BGTaskScheduler.shared.register(forTaskWithIdentifier: RefreshTaskID.daily,
                                    using: nil) { task in
        handleDailyRefresh(task as! BGAppRefreshTask)
    }
    scheduleNextRefresh()
    return true
}
 
func scheduleNextRefresh() {
    let request = BGAppRefreshTaskRequest(identifier: RefreshTaskID.daily)
    // Ask for something too soon and the system rounds it into a window you did not intend.
    request.earliestBeginDate = Calendar.current.date(byAdding: .hour, value: 6, to: Date())
    do {
        try BGTaskScheduler.shared.submit(request)
    } catch {
        NSLog("[app] submit failed: \(error)")
    }
}
 
func handleDailyRefresh(_ task: BGAppRefreshTask) {
    // Queue the next run first. Forget this and you get exactly one refresh, ever.
    scheduleNextRefresh()
 
    let work = Task {
        let picked = await DailyWallpaperPicker.pickNext()
        SharedStore.write(picked)                     // writes into the App Group container
        WidgetCenter.shared.reloadTimelines(ofKind: RefreshTaskID.widgetKind)
        task.setTaskCompleted(success: true)
    }
 
    task.expirationHandler = {
        work.cancel()
        task.setTaskCompleted(success: false)
    }
}

The order of the write and the reload is not interchangeable. Call reloadTimelines first and the widget simply re-reads the old value. I got this backwards once and watched a symptom I had already fixed come back.

If you still need the extension to request work, keep submit there and leave register plus the handler in the host app. Thinking of it as requester and recipient rather than one owner makes the whole layout easier to hold in your head.

Two budgets, and confusing them will misdirect your debugging

There is a deeper point here that I misread for a long time. More than one budget is involved.

The first is whether a BGAppRefreshTask gets a chance to run at all, which is the system's call based on usage patterns, battery and connectivity. The second is how often WidgetKit will redraw a timeline; as the WidgetCenter reference notes, you can request a reload but immediate execution is not promised.

Treat those as one budget and your diagnosis will drift. Here is how I tell them apart.

The evening-freeze case is one I wrote up separately in why an iOS widget keeps showing stale data. What this article covers sits one layer earlier: who wakes up in the first place.

Do not trust a true from submit

To keep silent failures visible, I made both the scheduling and the execution report on themselves. Pending requests are readable through getPendingTaskRequests. Execution is recorded by writing a timestamp into the App Group from inside the handler and surfacing it on a debug screen.

// A self-reporting view I keep in the settings screen of development builds
import BackgroundTasks
import SwiftUI
 
struct RefreshDiagnosticsView: View {
    @State private var pending: [String] = []
    @State private var lastRun: Date? = SharedStore.lastRefreshAt()
 
    var body: some View {
        List {
            Section("Pending requests") {
                if pending.isEmpty {
                    Text("None — submit may have returned true and the request still vanished")
                } else {
                    ForEach(pending, id: \.self) { Text($0) }
                }
            }
            Section("Last run") {
                Text(lastRun.map { $0.formatted() } ?? "no record")
            }
        }
        .task {
            let requests = await BGTaskScheduler.shared.pendingTaskRequests()
            pending = requests.map(\.identifier)
        }
    }
}

The reading order is fixed. Empty last-run timestamp means the host app is not waking, so I check the identifier and the Info.plist. Fresh timestamp with a stale display means it did wake, so I check the reload side instead. Splitting it into those two questions cut my debugging time noticeably.

For the ways Code=1 shows up, I have the causes laid out in tracking down BGTaskScheduler.submit Error Code=1. Read together with this piece, the extension-related gaps are covered as well.

Where interactive widgets stop short

Widgets can hold buttons from iOS 17 onward, so it is natural to want the image to change the moment one is tapped. Calling a reload from inside an AppIntent's perform(), though, has drawn repeated reports of minutes-long delays that reproduce only on device — one such thread on the developer forums collects several. My own results matched: instant in the simulator, a wait on hardware.

So I render the tap from the value I just wrote into the App Group, and let the system reload catch up afterwards. Responsiveness comes from my own write; correctness comes from the system's reload. Since splitting those two responsibilities, the simulator-versus-device gap has stopped costing me evenings.

The rules I kept after rolling this out to six apps

Rolling the same structure across six wallpaper apps, I wrote down three short rules so the decision would not wobble. Background refresh registration is the host app's job alone. Identifiers are read only from the shared constant. The reload request comes after the write, never before.

If you have a BGTaskScheduler call half-written in an extension target right now, try moving just the register line into the host app first. For me, relocating that single line was what finally made the morning screen change.

Thanks for staying with a problem this narrow. I hope the half day it cost me is one you get to keep.