iOS 27 Widget Not Updating: Debugging WidgetKit Timeline Reloads

Since the iOS 27 launch, the single most common support ticket for widget-using apps is some variation of “the widget stopped updating.” The instinct is to assume the iOS 27 widget not updating problem is a bug in the app’s refresh logic. In practice, the majority of these reports are not code defects at all — they are the widget timeline system behaving exactly as designed, against a developer mental model that assumes reloadTimelines(ofKind:) means “update now.”

This guide separates the four distinct failure modes that all present identically to the user: budget exhaustion, request coalescing, configuration staleness, and a genuinely broken provider. Diagnosing in the wrong order wastes days. Diagnosing in the right order usually resolves the ticket in an hour.

Key Takeaways

• reloadTimelines is a request, not a command. The system may execute it immediately, defer it, coalesce it, or drop it — and none of those outcomes raises an error.
• Budget accounting is per-widget-kind, not per-app. One chatty widget can starve a second widget in the same extension.
• The configuration the system holds is not necessarily the configuration you just wrote. Stale App Intent configuration reads as stale data.
• WidgetCenter introspection is the fastest way to distinguish “not running” from “running but rejected.” Log it before changing any code.
• For genuinely time-sensitive content, a widget is the wrong primitive. Use a Live Activity or push-updated widget instead of tightening a polling interval.

---

The “Why”: A Reload Is a Negotiation

The core misconception is that WidgetCenter.shared.reloadTimelines(ofKind:) is analogous to setNeedsDisplay. It is not. Widget rendering happens in a separate daemon that weighs your request against battery, thermal state, user engagement, and a per-kind daily budget. Your request enters a queue; what happens next is a policy decision you do not control.

+-------------------+     reload request      +---------------------+
|  Host Application | ----------------------> |   WidgetKit System  |
+-------------------+                         +---------------------+
                                                        |
                       +--------------------------------+--------------------------------+
                       |                |               |                |                |
                       v                v               v                v                v
                  Execute now       Defer          Coalesce         Drop (budget)    Drop (no provider)

Figure 1: The five possible fates of a single reload request. Only the first is visible to the developer.

Because none of the non-executing outcomes surfaces a diagnostic, the developer sees only “my widget didn’t change” and reaches for the nearest explanation. The rest of this article replaces that guess with an ordered diagnostic.

---

Diagnostic Order

Run these steps in sequence. Each one eliminates a class of cause and tells you whether to continue.

Step 1 — Is the provider executing at all?

Add a log at the top of the timeline(for:in:) implementation. If this never fires, the problem is upstream of the budget entirely — it is a provider crash, a missing extension target, or a build that never installed.

import WidgetKit
import OSLog

private let logger = Logger(subsystem: "in.iosdev.widget", category: "Timeline")

func timeline(
    for configuration: ProjectIntent,
    in context: Context
) async -> Timeline<ProjectEntry> {
    // Developer Thoughts: This single log line answers the most important
    // question first. If it never prints, stop debugging the budget.
    logger.notice("timeline requested, entryDate=\(Date(), privacy: .public)")
    ...
}

If the provider runs but the widget shows placeholder content, the provider is being invoked in snapshot context and the real timeline is being rejected. That points to Step 4.

Step 2 — Is the request being coalesced?

On the shipping 27.0.x builds, requests arriving in quick succession are frequently merged into a single execution. A write followed immediately by a reload can be absorbed into an in-flight reload, so the widget renders the state from before your write. Insert a yield between the persistence and the reload:

try await store.save(project)                  // write to the shared container
try await Task.sleep(for: .milliseconds(150))  // let the file coordinator publish
WidgetCenter.shared.reloadTimelines(ofKind: "ProjectWidget")

If adding the yield fixes the symptom, you had a coalescing problem, not a budget problem. Do not “fix” this by reloading more often.

Step 3 — Is the budget exhausted?

Budget is allocated per widget kind. Enumerate the kinds and inspect when each last ran. A widget that reports a stale lastModified far in the past despite frequent reload calls is budget-starved:

WidgetCenter.shared.getCurrentConfigurations { result in
    switch result {
    case .success(let configs):
        for config in configs {
            logger.notice("kind=\(config.kind, privacy: .public) family=\(String(describing: config.family), privacy: .public)")
        }
    case .failure(let error):
        logger.error("configurations failed: \(error)")
    }
}

If you are budget-starved, the answer is not to reload smarter. The answer is to reload less and update in place via push, or to move the frequently-changing surface to a Live Activity, which is not governed by the widget budget. See WidgetKit in iOS 27 and Live Activities: Dynamic Island Layout Customization.

Step 4 — Is the configuration stale?

The system stores the AppIntent configuration independently of your app. If that stored configuration references a deleted entity, a renamed project, or a changed identifier, the provider resolves nil and falls back to the placeholder — which the user reads as “not updating.” Re-resolve the entity defensively and always return a real entry when possible:

func timeline(for configuration: ProjectIntent, in context: Context) async -> Timeline<ProjectEntry> {
    // Never return placeholder for a real request unless nothing can be resolved.
    let project = configuration.selectedProject
        ?? (try? await ProjectEntityQuery().suggestedEntities().first)
        ?? ProjectEntity.fallback

    return Timeline(entries: [ProjectEntry(project: project)], policy: .after(.now.addingTimeInterval(1800)))
}

A nil selectedProject that silently degrades to a placeholder is the single most misleading “not updating” bug in the wild, because the placeholder looks like stale-but-valid content.

Step 5 — Is the shared container readable from both processes?

The extension and the app run in separate processes with separate sandboxes. A file written to the app’s Documents directory in the app process is invisible to the widget. Confirm both targets use the same App Group identifier and that the read path resolves the shared URL:

guard let container = FileManager.default.containerURL(
    forSecurityApplicationGroupIdentifier: "group.in.iosdev.shared"
) else {
    logger.fault("App Group container unavailable — check entitlements on BOTH targets")
    return
}

A missing App Group entitlement on the extension (as opposed to the app) produces this failure selectively: everything works in the simulator with a shared process, and only fails on device.

---

The Verdict: Resisting the Refresh-Interval Reflex

The temptation when a widget “doesn’t update” is to shorten its refresh interval or call reloadAllTimelines() from more places. Both make the situation worse: tighter polling burns budget faster and leaves the widget stale for longer stretches of the day.

When a widget is the right primitive

• Content that changes on the order of tens of minutes. Weather, calendars, progress summaries — anything where “fresh within the last half hour” is acceptable.
• Content the user can pull by opening the app. The widget is a convenience surface, not a real-time display.

When a widget is the wrong primitive

• Anything the user expects to watch update. Scores, delivery tracking, live progress. Use a Live Activity.
• Server-driven state with unpredictable change times. Use push-updated widget timelines rather than polling.

The Hidden Cost

• Silent failure is the design. Every non-executed reload returns normally. There is no error to catch and no retry signal. The only reliable instrumentation is your own logging plus WidgetCenter introspection.
• Budget is shared per kind. Teams that add a second, chattier widget to the same extension are often surprised to find the first widget stopped updating. Budget was consumed by its sibling, and nothing in the first widget’s code changed.

The verdict: treat the widget timeline as a scarce, shared, best-effort resource. If your product requirement cannot tolerate the budget, the requirement is pointing you at Live Activities — not at a more aggressive reload strategy.

---

Internal Links

• WidgetKit in iOS 27: App Intent-Driven Widgets with Dynamic Styling — The architecture this diagnostic builds on, including the reload budget model.
• Live Activities in iOS: Dynamic Island Layout Customization — The correct primitive when content must update faster than the widget budget allows.

References & Further Reading

• Apple Developer Documentation — WidgetKit for WidgetCenter, timelines, and widget budgets.
• Apple Developer Documentation — Keeping a widget up to date for the authoritative description of reload policies.
• Apple Design — Widgets HIG for expectations around freshness and glanceability.