Mobile State Management | The Garnet Wiki

Mobile state management is the discipline of tracking, persisting, and synchronizing data across app launches, network conditions, and device boundaries. It matters whenever an application must remember user context after a background kill, resume a partial workflow on restart, or maintain consistency when connectivity drops and recovers. Poor state management produces the most common failure mode in mobile: data that vanishes without error, UI that reflects stale decisions, or sync that silently corrupts local records. This page addresses the mechanics of managing state reliably, the tools real teams use to inspect and control it, and the failure patterns that catch teams off guard.

Persisting state across launches

The most fundamental question in mobile state management is what survives an process termination. On iOS, the system may kill a backgrounded app at any moment; on Android, the OS can reclaim memory under pressure. The pattern that works across platforms is to store minimal essential state in a location the OS guarantees persists, then reconstruct full context on launch.

File-based primitives

The simplest persistence layer is key-value storage. On macOS and iOS, the defaults command reads and writes the property list files the system uses for user defaults. To store a boolean flag indicating whether a onboarding flow has been seen:

defaults write com.example.app hasSeenOnboarding -bool true

To read it back:

defaults read com.example.app hasSeenOnboarding

The stored value lives in ~/Library/Preferences/com.example.plist. On Android, the equivalent is SharedPreferences, accessed through the android.preference framework, but the mechanical pattern is identical: map a key to a primitive type (boolean, int, float, string, or set) and read it on startup. Neither platform guarantees schema enforcement — writing a string where a boolean was expected produces undefined behavior, typically a crash or silent corruption.

SQLite for structured state

When state includes relationships, timestamps, or queryable history, a lightweight database is the standard approach. sqlite3 is the real command-line tool shipped with every major OS and is routinely used to inspect mobile application databases.

To create a table tracking the last sync timestamp per user context:

CREATE TABLE IF NOT EXISTS sync_state (
  user_id TEXT NOT NULL,
  last_sync INTEGER NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  PRIMARY KEY (user_id)
);

To insert or update the timestamp after a successful network sync:

INSERT INTO sync_state (user_id, last_sync, status) 
VALUES ('user_123', CAST(strftime('%s','now') AS INTEGER), 'synced')
ON CONFLICT(user_id) DO UPDATE SET last_sync = CAST(strftime('%s','now') AS INTEGER), status = 'synced';

To read the current state before attempting a reconnect:

SELECT last_sync, status FROM sync_state WHERE user_id = 'user_123';

SQLite files are ordinary files on disk (typically at ~/Library/Application Support/iOS Simulator/*/Library/Preferences/ on iOS simulator, or ~/app_database.db on Android with assets baked in). They survive app restarts and OS kills. The sharp edge: if two processes write to the same SQLite file without WAL (Write-Ahead Logging) or proper file-locking, the last writer wins and earlier changes may be lost without error. Enabling WAL mode is a one-time configuration:

PRAGMA journal_mode=WAL;

This persists across connections and prevents the "database is locked" error that silently drops writes during concurrent UI and sync processes.

Keychain for sensitive state

Credentials, tokens, and cryptographic keys belong in the keychain, not in plain files or defaults. On iOS, the security command manages keychain items. To store a token:

security add-generic-password -a com.example.app -s "auth_token" -w "glhf_secret_token"

To retrieve it:

security find-generic-password -a com.example.app -s "auth_token" -w

On Android, the KeyStore system provides equivalent isolation. The mechanical pattern is always: never store secrets in defaults or asset files; always use the platform-provided secrets manager. The sharp edge: keychain items have service-and-account bindings. If the app's bundle identifier changes or the account string is altered, the item becomes invisible and is effectively lost. There is no "migrate" command — the developer must explicitly read the old item, then write it under the new key.

Managing UI state within a session

Not all state needs to survive a launch. Temporary UI state — selected tabs, form input, modal dismissal status — lives only for the duration of the current session. The pattern that scales is to keep UI state in memory and serialize only what must persist.

Deep linking and state restoration

When an app is launched from a deep link, the URL often carries context that must be captured before the main UI builds. A real pattern used by shipping apps is to parse the incoming URL in application:willFinishLaunchingWithOptions: (iOS) or onCreate (Android), extract the relevant query parameters, and store them in a short-lived state object that the root router consumes.

For example, a URL like myapp://profile?user_id=42&section=settings might be processed thus:

// iOS example (simplified)
NSDictionary *components = @{@"user_id": @"42", @"section": @"settings"};
NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
[defaults setObject:components forKey:@"deep_link_context"];

On the next launch, the root view controller reads this defaults entry and navigates to the correct section. The key is that this key is cleared or overwritten on every launch — it is not a persistence mechanism, but a one-time handoff.

The sharp edge: if the app is terminated by the OS before applicationDidFinishLaunching runs, the defaults write may not reach disk. Additionally, if the deep link carries sensitive parameters (tokens, PII), persisting them in user defaults creates a security exposure. In those cases, the pattern is to pass the data only to the specific view controller that needs it, not to the global defaults store.

Form state and input restoration

Modern text fields on both iOS and Android support automatic restoration of user input after a restart, but this behavior is opt-in and varies by platform version. On iOS, setting textField.autocorrectionType = .no and textField.spellCheckingType = .no disables the feature entirely. To enable restoration for a specific field:

textField.textContentType = UITextContentTypeUsername;
textField.autocorrectionType = .no;

On Android, the android:importantForAutofill attribute controls whether a view group participates in autofill. Setting it to yes or respective allows the system to save and restore text across launches.

The failure mode: if a text field has secureTextEntry enabled (as for passwords), the system never restores the value, and the field appears empty after a restart. Teams often mistake this for a bug in their restoration logic when it is actually platform-enforced behavior. The fix is to handle the empty state explicitly in code rather than expecting the system to preserve secrets.

Network synchronization and offline-first

The offline-first pattern is the standard approach for state that must remain consistent across connectivity boundaries. The core idea is: the local database is the source of truth. Network operations are retries or optimizations, not the mechanism that makes data available.

Conflict resolution basics

When a device edits a record offline and the same record is edited on the server, a conflict arises. The simplest real pattern is last-write-wins, using a server-assigned timestamp or version vector. The local client stores the version alongside each record:

CREATE TABLE notes (
  id TEXT PRIMARY KEY,
  content TEXT,
  server_version INTEGER DEFAULT 0,
  local_modified INTEGER NOT NULL
);

When the device reconnects and sends pending changes, the server responds with its current version. The client then compares:

If server_version > local.server_version: the server won; discard local changes or present a merge UI.
If local.server_version >= server_version: the local copy is current; acknowledge the server's response.

A more sophisticated pattern uses operational transformation (OT) or conflict-free replicated data types (CRDTs) for collaborative editing scenarios, but these require custom data structures and are beyond the scope of basic sync.

Retry and backoff

Network calls that fail due to transient connectivity should not be retried blindly. A concrete real pattern is exponential backoff with jitter. The pseudocode that ships in many production clients looks like:

def retry_with_backoff(operation, max_tries=5):
    for attempt in range(max_tries):
        try:
            return operation()
        except TransientError:
            if attempt == max_tries - 1:
                raise
            delay = (2 ** attempt) * 0.1 + random.uniform(0, 0.1)
            time.sleep(delay)

The 0.1 base and the random.uniform jitter term prevent the "thundering herd" problem where thousands of devices all retry at exact multiples of the same interval, overwhelming the backend. The sharp edge: if the backoff calculation uses wall-clock time and the device clock is skewed (common on older devices or after OS restarts), the intervals drift and retries may fire too early or never fire at all. Using time.monotonic() for the delay calculation avoids this class of bugs.

Inspecting sync state with curl

When a sync issue appears in production, the fastest way to diagnose is to query the backend directly. curl is the real tool used by every ops and engineering team for this. To check the current sync state for a user via a REST endpoint:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/users/user_123/sync-state

A typical successful response might look like:

{
  "user_id": "user_123",
  "last_sync_timestamp": 1704067200,
  "pending_changes": 3,
  "status": "idle"
}

If the response returns 404 Not Found, the user record may not have been provisioned on the sync service, or the token lacks the required scope. If it returns 503 Service Unavailable, the sync backend itself is down — no amount of client retry logic will succeed until the service recovers. The pattern is to surface these HTTP codes to the user as "sync unavailable" rather than looping retries that produce no visible progress.

Debugging and inspecting state

When state goes wrong, the right inspection tool depends on where the state lives.

System logs

On any Linux-based system (including Android's adb shell), journalctl shows the systemd service logs. To filter for a specific mobile app's output:

journalctl -u myapp.service -f

The -f flag tails the log, which is essential when reproducing a race condition that only appears under specific timing.

On iOS, the Console app aggregates os_log and print statements. To search for a specific state-related message:

sudo log show --predicate 'processImagePath contains "myapp"' --last 1h

Database inspection

When the state lives in SQLite, sqlite3 is the direct inspection path. To list all tables and their row counts in the app's database:

sqlite3 ~/Library/Application\ Support/iOS\ Simulator/*/Library/Preferences/app_database.db "SELECT name, (SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=t.name) FROM sqlite_master WHERE type='table';"

To view the contents of the sync_state table mentioned earlier:

sqlite3 app_database.db "SELECT * FROM sync_state;"

This reveals exactly what the client thinks it knows about last sync, which often contradicts what the backend reports — a common source of "sync is broken" tickets.

Git for state history

When state changes are tracked as code configuration (feature flags, remote endpoints, TLS settings), git is the real tool for auditing. To see who changed a feature flag and when:

git log --all --oneline -- path/to/feature_flags.yaml

To see the exact diff that introduced a change:

git show a1b2c3d:path/to/feature_flags.yaml

This is how teams investigate production incidents where a flag was toggled at an unexpected time and they need to reconstruct the exact sequence of events.

Sharp edges — what silently fails

Defaults plist corruption

The defaults plist is a binary property list. If it becomes corrupted — often from concurrent writes, abrupt shutdowns, or filesystem errors — defaults read will throw an error like:

The domain/default pair (com.example.app, hasSeenOnboarding) does not exist

or more cryptically:

2025-01-15 10:23:41.123456+0000 defaults[12345] <Error>: 0x1a2b3c <private>: CFPropertyListCreateFromXMLData returned -1

The fix is to delete the plist file entirely (it regenerates on next write) or use plutil to validate and convert:

plutil -convert xml1 ~/Library/Preferences/com.example.plist

SQLite WAL abandonment

If a process crashes while WAL mode is active but before the WAL checkpoint completes, the WAL file may remain on disk after the database closes. On next open, SQLite may report:

database is locked

or refuse to open entirely until the WAL is resolved. The real command to fix this on macOS/Linux is:

sqlite3 app_database.db "PRAGMA wal_checkpoint(TRUNCATE);"

If that fails, removing the -wal and -shm sidecar files alongside the main .db file resets the database to a clean state, at the cost of any uncommitted WAL transactions.

Keychain access after bundle ID change

If an app's bundle identifier is changed post-deployment (a rare but documented migration path), all keychain items stored under the old identifier become inaccessible. The security command will return -25301 (item not found). There is no automatic migration path. The development team must implement custom logic to read the old item and re-store it under the new service name, typically during the first launch after the ID change. This is one of those "you only learn after it breaks in production" moments.

Autofill vs. secure text entry

On iOS, UITextContentType values like .username and .password trigger the system autofill UI. However, if a text field has secureTextEntry = true, the system never suggests autofill options. Teams building login forms often become confused when the password field offers no suggestions while the username field does — the fix is to separate the fields or use textContentType = .oneTimeCode for verification codes, which always presents the system UI regardless of secure entry status.

Offline flag state vs. network reachability

A common confusion is equating "app is in background" with "network is unavailable." The app may be backgrounded on Wi-Fi with full connectivity, or foregrounded on cellular with no signal. State management logic must check actual network reachability (via Reachability, NetworkInfo, or NetInfo) rather than assuming foreground = online. The sharp edge: reachability APIs may report "connected" even when the DNS resolution fails or the TCP handshake times out, leading to attempted writes that silently fail. The pattern is to attempt the write and handle the specific error (timeout, connection refused, cancelled) rather than pre-checking reachability.

Production breakage patterns

The most common production incident in mobile state management is silent data loss during OS-initiated terminations. A user edits a draft, the OS kills the app to free memory, the user reopens the app, and the draft is gone. No error was shown, no crash log was produced — the data simply wasn't persisted. The post-mortem typically reveals that the edit was stored only in an in-memory UI state object, with no fallback to defaults, keychain, or SQLite.

Another frequent pattern is the "zombie sync": the app believes it's syncing because the retry loop has run three times with exponential backoff, but each retry returns 409 Conflict due to a version mismatch that the client never parses. The sync loop logs retry #3 completed and marks the operation as successful locally, but the server never received the payload. The result: the local state says "synced," the server says "pending," and the next launch re-reads the local "synced" flag and skips the actual push, permanently stranding the data on the device.

A third pattern involves feature flags stored in remote config that the client caches at launch. If the remote config service changes a flag value, the client remains on the old value until the next app launch fetches the updated config. In production, this means a rolled-back flag may still be active for users who haven't relaunched the app in 24+ hours. The sharp edge: there is no built-in mechanism to force a config refresh mid-session without a full app restart. Teams working around this often build a "refresh config" action in the settings screen, which triggers a curl-like fetch of the remote config endpoint and overwrites the local cache.

Summary

Mobile state management reduces to three concentric layers: what survives an OS kill (persistent store), what survives a session (UI state), and what survives a network partition (offline-first sync). The real tools — defaults, sqlite3, security, curl, journalctl, git — are the same ones used across the industry. The failure modes are predictable once you know where state lives: plist corruption, WAL abandonment, keychain binding loss, autofill secure-text interaction, and reachability assumption bugs. The pattern that prevents the majority of incidents is explicit persistence at every boundary: write to the database before acknowledging UI success, read from the database before displaying restored state, and always inspect the backend with curl when sync appears stuck. There is no magic framework that handles all of this automatically — the discipline of choosing the right store for each piece of state, and the discipline of inspecting that store when things go wrong, is what separates shipping, reliable mobile applications from ones that lose data in production.

This page was rewritten on 17 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.