Safe mode

Let's talk about crashes.

a Windows crash screen

"Crash" is a computing term for software doing something so bad that it has no choice but to completely shut down. For iPad and other mobile-platform apps, this presents as an app you're using suddenly dropping you back at the device home screen.

Crashes tend to happen where the complexity of the software lies. And Muse is visually complex in its rendering: PDFs show their first few pages; boards recursively show all their contents; link cards fetch information from the web page like icon and title. If it turns out that something in the rendering path causes a crash, it's possible that reloading the same board will result in another crash right away. We call this unfortunate state a "crash loop."

Crash loops are particularly bad when they happen on the user's home board: now they are completely locked out of their Muse data.

To date this has only happened twice. In those cases, the user has written to our support email, and we've been able to inspect the crash analytics, figure out a fix, and get it to the user within a day or two via TestFlight. But even that best-case scenario is lackluster at best.

While we work hard to protect against crashes of all sorts, it's unrealistic to think we'll ever eliminate all of them. Thus, we need a fallback: something that gives the user some ability to access their data and guidance on next steps, even though the app is not working properly.

Prior art: Windows and Mac safe mode

Operating systems have a solution for this: Mac safe mode and Windows safe mode.

Mac safe mode screenshot Windows safe mode screenshot

Safe mode uses a minimum of advanced capabilities: lower resolution, no special drivers, no (or optional) network access, etc. The idea here is to bootstrap the computer into a state where it's possible to inspect and tinker with the system, but in a way less likely to trigger problems. Often the display is minimalist or even ugly, and you can't run most programs: but that's ok, because you just want to perform some recovery action.

Think of safe mode like driving a car on a spare tire: it can't go as fast or as far, but it's probably enough to get you to a repair shop.

Goals for Muse's safe mode

How it works

If you Muse crashes three times within two minutes, it will start up next time in safe mode.

screenshot of Muse in safe mode

The two data export options (full content export, and debug logs) are the same as those available in the Settings → Support menu during normal operation of the app. Importantly, the full data export does very little processing: it's just a zip file with everything from your Muse filesystem, including lots of redundant (cached) data that wouldn't show up in a Muse bundle export.

From here the user can pull out any important asset from the exported data. They can also (if they feel comfortable doing so) send the entire dataset to the Muse team so that we can more quickly debug the problem.


We hope you'll never need safe mode, but it's good to know it's there.

Follow Muse development

✅ Thanks—check your email to confirm your subscription.