When an unexpected, severe error occurs in CircuitPython, CircuitPython will enter safe mode. An error that causes safe mode is so serious that it is not possible to proceed; otherwise CircuitPython would raise a Python exception, which you could catch and handle. You can also initiate safe mode yourself manually or in your CircuitPython program.

Safe mode prevents boot.py and code.py from running until you exit safe mode. It also enables running a special file called safemode.py that can exit safe mode automatically.

There are multiple possible causes for safe mode:

  • An unexpected software error occurred, possibly due to a bug in CircuitPython or underlying software that it uses.
  • A hardware failure occurred.
  • The power dipped to too low a voltage.
  • There is an error in boot.py or safemode.py.
  • Some CircuitPython code deliberately entered safe mode.
  • You pressed one or more buttons to enter safe mode manually. You may want to do this if boot.py or code.py are doing something you cannot recover from, such as restarting over and over, or setting CIRCUITPY to be read-only.

When safe mode is triggered, CircuitPython saves the reason for going into safe made, and then forces a hard reset of the board. After the reset, it skips running boot.py and code.py, as mentioned. Instead, it simply prints the reason for safe mode on the console. You can then enter the CircuitPython REPL, edit files on the CIRCUITPY drive to fix the problem to clear safe mode, or just press RESET again, if the problem is transient.

For instance, here is the kind of thing you would see in the console if there was a power problem:

Auto-reload is off.
Running in safe mode! Not running saved code.

You are in safe mode because:
The power dipped. Make sure you are providing enough power.
Press reset to exit safe mode.

Press any key to enter the REPL. Use CTRL-D to reload.

Adafruit CircuitPython 8.1.0 on 2023-03-30; Adafruit Feather RP2040 with rp2040

In the rest of this guide, you'll learn:

  • More about the details of the causes of safe mode
  • How to enter safe mode deliberately
  • How to recover from safe mode, manually or using safemode.py

This guide was first published on Mar 01, 2023. It was last updated on Mar 08, 2024.

This page (Overview) was last updated on Mar 08, 2024.

Text editor powered by tinymce.