From time to time, an error occurs when working with CircuitPython. Here are a variety of errors that can happen, what they mean and how to fix them.
File system issues¶
If your host computer starts complaining that your
CIRCUITPY drive is corrupted
or files cannot be overwritten or deleted, then you will have to erase it completely.
When CircuitPython restarts it will create a fresh empty
This often happens on Windows when the
CIRCUITPY disk is not safely ejected
before being reset by the button or being disconnected from USB. This can also
happen on Linux and Mac OSX but its less likely.
CIRCUITPY filesystem and reload CircuitPython.
To reload CircuitPython (for example, to correct a corrupted filesystem), follow the process below. It’s important to note that any files stored on the ``CIRCUITPY`` drive will be erased.
- Download the appropriate flash erase uf2 from here.
- Double-click the reset button.
- Copy the appropriate .uf2 to the xxxBOOT drive.
- The on-board NeoPixel will turn blue, indicating the erase has started.
- After about 15 seconds, the NexoPixel will start flashing green. If it flashes red, the erase failed.
- Double-click again and load the appropriate CircuitPython .uf2.
This error occurs when importing a module that is stored as a
mpy binary file
(rather than a
py text file) that was generated by a different version of
CircuitPython than the one its being loaded into. Most versions are compatible
but, rarely they aren’t. In particular, the
mpy binary format changed between
CircuitPython versions 1.x and 2.x.
So, if you just upgraded to CircuitPython 2.x from 1.x you’ll need to download a
newer version of the library that triggered the error on
import. They are
all available in the
and the Community bundle.
Make sure to download a version with 2.0.0 or higher in the filename.