Stuck-state recovery

A patron's app is in a state that sign-out + uninstall + reinstall does not fix. This console walks you through the six-step recovery workflow.

When to use this workflow

Use this whenever a patron's app is in a stuck state that ordinary sign-out and reinstall does not clear. Typical signals:

A book loaded once, then refuses to load on every subsequent open.
The patron has already tried sign-out → uninstall → reinstall and the failure persists.
The same credentials work on a different device — i.e. the failure is tied to the device, not the patron or the title.
The patron sees a recurring error overlay or alert that retrying does not clear.
"It's hit or miss" / "sometimes it works, sometimes it doesn't" on the same checkout.

Reset Account is a general-purpose local-state recovery for one library — it is not targeted at a specific bug. Use it as the first recovery step whenever ordinary sign-out has not been enough.

Confirm patron is on Palace 3.1.0 or later

▼

Reset Account ships in Palace iOS 3.1.0 — it does not exist on 3.0.3 or earlier.

Ask the patron: open the Palace app → Settings → scroll to the bottom. The version is shown as "Palace 3.1.0 (build n)".

If 3.1.0+ → continue to Step 2.
If 3.0.3 or earlier → ask them to update from the App Store first, then come back.

Get the patron's Device ID

▼

Tell the patron:

Open the Palace app, then go to Settings → Developer Settings → Send Error Logs. You'll see a Device ID near the top — it looks like 12345678-90AB-CDEF-1234-567890ABCDEF. Tap Copy Device ID and paste it into your reply.

If they don't see "Developer Settings": ask them to go to Settings, scroll to the bottom, and long-press the Palace version label until Developer Settings appears.

Inline tool

Paste the Device ID — auto-generates the Firebase parameter name

Device ID from patron (with dashes)

Sanitized (dashes stripped)

Paste a Device ID above

Firebase Remote Config parameter name copy this

Paste a Device ID above

Enable the Reset flag in Firebase Remote Config

▼

Open Firebase Console → palace-iOS project → Remote Config.
Click Add parameter.
Parameter name: paste the one from Step 2's tool (starts with reset_account_enabled_device_).
Data type: Boolean.
Default value: true.
Description: Reset Account enabled for HelpSpot ticket #<NNNNN> — include the ticket number so we can audit later.
Click Publish changes. Propagation: usually under 5 minutes, up to 1 hour worst case.

Tip: double-check that the parameter is actually Published — Firebase has a "save draft" state that looks similar but won't fetch on the patron's device.

Walk the patron through the Reset

▼

Tell the patron:

Force-quit Palace (swipe up + flick the card away), then re-open it. Within an hour you should see a red Reset This Library Account button at the bottom of Settings → Accounts → [your library name]. Tap it and confirm. The app signs you out and returns to the library selection screen (5–10 seconds). Sign back in with your card + PIN and try the failing audiobook again.

If they don't see the red button: Remote Config hasn't fetched yet. Have them force-quit + re-open one more time. Worst case, give it 30 more minutes.

Verify the reset succeeded

▼

Primary check: ask the patron whether the previously-failing book now plays / downloads after they re-signed in.

Yes → success. Continue to Step 6.
No, but the error is different now → partial fix. Note the new error string and check the "If Reset didn't fix it" section below.
No, exact same symptom → the failure is below the local-state layer. See the escalation reference below.

Optional deep check — if the patron is comfortable sending a sysdiagnose, paste it below to verify every reset step actually ran.

Inline tool · optional

Sysdiagnose log verifier

Paste any log text containing [RESET_ACCOUNT] lines

Paste log text above and click Verify reset steps.

Cleanup — disable the per-device flag

▼

If Step 5 succeeded, turn the flag back off so the Reset button is hidden again on that device.

Firebase Console → Remote Config.
Find your reset_account_enabled_device_… parameter.
Either delete the parameter or change its value to false.
Click Publish changes.

If Step 5 did not succeed and you're escalating to engineering: leave the flag on. Engineering may need to ask the patron to retry on a diagnostic build.

Tag the HelpSpot ticket with reset-account and note the outcome (fixed / partial / no change) so we can track effectiveness.

Reference

If Reset didn't fix the patron — escalation tree

1. iCloud-restored bad state?

If iCloud Backup is enabled and the bad state lives in the backup, every reset gets clobbered by the next restore. Ask the patron to temporarily disable iCloud Backup for Palace (Settings → [name] → iCloud → Manage Account Storage → Backups → [device] → Palace → toggle off), do another Reset, then re-enable after the next successful checkout.

2. IdP-side session (SAML/OIDC libraries only)

The library's identity provider still has the patron's session active. Ask the patron to clear Safari cookies (Settings → Safari → Clear History and Website Data) and try again.

3. CM-side state corruption

Device-token rows or license fulfillment cache out of sync server-side. Ask the CM team to inspect the patron's account. Provide Device ID + library + failing book IDs.

4. A real client bug we haven't yet identified

Escalate to iOS engineering with: Device ID, failing book IDs, sysdiagnose if available, screenshots, and the verified log output from Step 5. Leave the per-device Firebase flag ON — engineering may ship a diagnostic build and ask the patron to retry.

What the patron loses when they Reset

Cleared on this device

Sign-in (will need to re-enter library card + PIN)
Downloaded book files (re-download from My Books after sign-in)
Local reading positions / bookmarks for any book that hasn't synced to the server yet — server-synced positions come back on sign-in
Adobe DRM device activation (re-activates automatically on next protected ebook open)

Not affected

The patron's library checkouts / holds (live on the server)
Server-synced bookmarks and reading positions
Other libraries the patron has added (Reset only touches the one selected library)
The patron's account at the library itself

Frequently asked questions

The patron is on Palace 3.0.3. Can I still help them?

Not with this workflow. Reset Account ships in 3.1.0+ only. Ask them to update from the App Store first. If they say the update isn't available, give it a day — it may still be rolling out to their region.

The patron doesn't see the red "Reset This Library Account" button after the flag was published.

Confirm: (1) they're on Palace 3.1.0+ — check Settings → version label; (2) you used the sanitized Device ID in the parameter name (no dashes); (3) they force-quit Palace and re-opened (Remote Config fetches on launch); (4) they're on Wi-Fi or stable LTE; (5) Firebase says Published, not Draft. Worst-case propagation is 1 hour.

Will the patron lose other libraries they've added?

No — Reset only touches the one library you walk them through. If they have multiple libraries, the others are untouched.

The patron sees "A Problem Has Occurred" overlay in the player — is this the same bug?

Likely yes. That overlay is the toolkit's generic mapping for unmapped playback errors and is one of the three known surfaces of the stuck-state pattern. Reset is the same recommendation.

Is the Device ID personally identifiable?

No. It's a random UUID generated on first launch and stored in app UserDefaults — not the iOS identifierForVendor, not tied to the Apple ID. It rotates if the patron uninstalls and reinstalls.

The patron got disconnected mid-reset. What now?

Reset proceeds unconditionally — every step runs regardless of whether the previous one's network call succeeded. Local state IS cleared even if the network dropped. They should just sign back in and try the failing book.

Reset worked once but the patron is back a week later. Re-run it?

Yes, safely. The flag stays in Firebase Remote Config until you disable it — if the patron is recurring, leave the flag on and they can self-recover. If the pattern repeats, that's a strong signal of an underlying client bug — escalate to iOS engineering with the timeline + Device ID + book IDs.

Technical detail (for engineering hand-off)

Full implementation: Palace/SignInLogic/TPPSignInBusinessLogic+ForceReset.swift.

What Reset Account clears, in order

FCM device token DELETE on the Circulation Manager (best-effort, never gates)
bookDownloadsCenter + bookRegistry state for the selected library
Adobe DRM device deauthorize (RMSDK clears local activation files regardless of network result)
Keychain credentials (userAccount.removeAll), selectedIDP, samlHelper.clearState
NetworkExecutor cache + URLCache.shared.removeAllCachedResponses() — addresses CFNetwork-cached stale fulfillment URLs surviving uninstall
One-shot flag for next OIDC sign-in to force prefersEphemeralWebBrowserSession = true
WKWebsiteDataStore.default() — every data type, from epoch

What Reset Account does NOT touch

CM-side device-token rows (CM team intervention needed)
IdP-side session
iCloud-backup-restored stale state on next launch
Server-synced bookmark / position records (intentional — patron keeps their place)

Expected log signature

[RESET_ACCOUNT] start — libraryAccountID=<uuid>
[RESET_ACCOUNT] step 1 ok — FCM token DELETE dispatched
[RESET_ACCOUNT] step 2 ok — bookDownloadsCenter + bookRegistry reset
[RESET_ACCOUNT] step 2.5 — dispatching DRM deauthorize
[RESET_ACCOUNT] step 3 ok — userAccount.removeAll, selectedIDP=nil
[RESET_ACCOUNT] step 4 ok — networkExecutor cache + URLCache cleared
[RESET_ACCOUNT] step 5 ok — nextOIDCSessionEphemeral flag set
[RESET_ACCOUNT] step 6 ok — WKWebsiteDataStore wiped
[RESET_ACCOUNT] complete

Gating

Mechanism	Firebase parameter	Default
Per-device (support)	`reset_account_enabled_device_<id>`	n/a
Global rollout	`reset_account_enabled`	`false`
QA local override	`RemoteFeatureFlags.resetAccountLocalOverride` UserDefault	unset

Source markdown: docs/Operations/reset-account-stuck-state-workflow.md · Implementation: Palace/SignInLogic/TPPSignInBusinessLogic+ForceReset.swift · Linked: HelpSpot 17716, 17929, 17964, 17981 · JIRA PP-4282