Skip to main content

​
Categories

CategoryDescriptionExample
networkNo connection or request timed outSync failed, no internet
authSession expired or credentials rejectedToken invalid
sync_conflictSame record modified on two devices while offlineLast-write-wins applied
corrupted_local_stateDrift database integrity failureUnreadable record
algorithm_failureMana engine returned an invalid or out-of-range resultPool calculation error
unexpectedAny error that does not match a known categoryUnhandled exception

​
UI behaviour by category

CategoryUser action shownUrgency
networkTry again when connectedNone
authSign in againNone
sync_conflictNo action needed (resolved automatically)None
corrupted_local_stateContact supportLow
algorithm_failureRestart app; contact support if it continuesLow
unexpectedTry again; contact support if it continuesNone
No error category uses urgent, alarming, or guilt-inducing language. The tone must stay consistent with the Product Contract regardless of severity.

​
Copy rules

  • No blame. Never frame the error as the user’s fault.
  • No urgency by default. Do not use exclamation marks or alarming phrasing.
  • Provide a safe next step. Every error message must give the user one clear, low-effort action or explicitly tell them no action is needed.
  • Avoid technical language. Don’t expose error codes, stack traces, or internal identifiers in user-facing copy.

​
Examples by category

Banned: “Connection failed. Please check your internet.”Use: “Couldn’t sync right now. It will try again when you’re connected.”
Banned: “Your session has expired. You must sign in again.”Use: “You’ve been signed out. Sign in again to continue.”
Banned: “Conflict detected. Changes may have been lost.”Use: Nothing shown to the user in most cases. If shown: “A small update was applied in the background.”
Banned: “Database error. Your data may be corrupt.”Use: “Something went wrong with your data. If this keeps happening, contact support and we’ll help.”
Banned: “Mana calculation error. Please restart.”Use: “There was a problem loading your plan. Restarting the app usually fixes this.”
Banned: “An unexpected error occurred.”Use: “Something didn’t work as expected. Try again, and contact support if it keeps happening.”

​
Logging rules

  • Redact task titles. If the user has opted out of data sharing, task titles must not appear in logs.
  • Redact check-in values. Raw [body, mind, mood] scores are sensitive health data - never log them in plain text.
  • Log the error category and code path. Enough context to reproduce the issue, not enough to reconstruct private content.
  • Include the version. App version and database schema version must accompany every error log.
// Correct - logs category and location, no user content
log.error('algorithm_failure in ManaEngine.computePool', error: e, stackTrace: st);

// Incorrect - exposes task title
log.error('Failed to price task "${task.title}"', error: e);