bug: PouchDB "unknown_error" on iOS Safari prevents saving documents

[sleidig]

Sentry Issue

AAM-DIGITAL-6RN — 3 occurrences since 2026-03-24, all on iPhone / Mobile Safari

Error

unknown_error: Database encountered an unknown error

PouchDB's generic catch-all error (HTTP 500) when it encounters an IndexedDB operation failure it can't categorize.

Affected Users / Environment

Field	Value
Device	iPhone (all occurrences)
Browser	Mobile Safari 18.6, 26.3, 26.4
OS	iOS 18.6.2, 18.7
Release	ndb-core@3.74.0
Pages	/mentor/:id/, /child/:id/

Analysis

This is a PouchDB + iOS Safari IndexedDB reliability issue. iOS Safari's IndexedDB implementation can sporadically fail:

• Storage pressure — iOS aggressively evicts IndexedDB data when storage is low
• Background/foreground transitions — iOS Safari may interrupt IndexedDB transactions when the app is backgrounded
• IndexedDB transaction aborts — some iOS versions have bugs in their IndexedDB implementation that can abort transactions unexpectedly

All events occur shortly after a completed sync (~10-20 seconds), suggesting the error is triggered during a subsequent PouchDB operation — likely the next live sync cycle, the changes feed, or a user-initiated save.

Error Propagation

When IndexedDB fails, PouchDB's internal error can escape outside the normal Promise chain (via aborted transactions / callbacks), bypassing all application-level try/catch. The error reaches Angular's global error handler as unhandled.

Save path (entity form → EntityFormService.saveChanges() → EntityMapperService.save() → PouchDatabase.put()) has proper try/catch and shows the user a "Could not save" alert. However, if the IndexedDB is in a broken state, subsequent PouchDB operations (live sync, changes feed) also fail and are not always caught.

Impact on Users

When IndexedDB is in a bad state:

1. Saves fail — PouchDatabase.put() throws, user sees a "Could not save..." alert
2. Sync fails — background sync can't read/write to local storage
3. The database may partially recover on subsequent attempts if iOS releases IndexedDB

Possible Mitigations

1. Better user guidance: Detect unknown_error from PouchDB and show a helpful message suggesting the user reload the page or clear browser data
2. Temporary remote-only fallback: If local PouchDB operations repeatedly fail, switch to remote-only mode (already supported via isInRemoteOnlyMode) so users can still save directly to the server
3. Test with newer indexeddb adapter: Production defaults to use_indexeddb_adapter: false (legacy idb adapter). The newer adapter may handle iOS error cases more robustly

[coderabbitai]

🔗 Related PRs

#3704 - new indexeddb adapter crashes after reloading app once [merged]
#3741 - fix(support): add database migration info for troubleshooting [merged]
#3755 - Use PouchDB.purge() to remove entities without permissions [merged]
#3773 - feat: change default pouchdb adapter indexeddb [merged]
#3825 - Fix/sync error analyis [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[sentry]

Sentry Issue: AAM-DIGITAL-6RN