circuitpython/docs/troubleshooting.rst

Troubleshooting
===============

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 ``CIRCUITPY`` filesystem.

Corruption 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 it's less likely.

.. caution:: To erase and re-create ``CIRCUITPY`` (for example, to correct a corrupted filesystem),
    follow one of the procedures below. It's important to note that **any files stored on the**
    ``CIRCUITPY`` **drive will be erased. Back up your code if possible before continuing!**

REPL Erase Method
^^^^^^^^^^^^^^^^^
This is the recommended method of erasing your board. If you are having trouble accessing the
``CIRCUITPY`` drive or the REPL, consider first putting your board into
`safe mode <https://learn.adafruit.com/welcome-to-circuitpython/troubleshooting#safe-mode-3105351-22>`_.

**To erase any board if you have access to the REPL:**

#. Connect to the CircuitPython REPL using a terminal program.
#. Type ``import storage`` into the REPL.
#. Then, type ``storage.erase_filesystem()`` into the REPL.
#. The ``CIRCUITPY`` drive will be erased and the board will restart with an empty ``CIRCUITPY`` drive.

Erase File Method
^^^^^^^^^^^^^^^^^
**If you do not have access to the REPL, you may still have options to erase your board.**

The `Erase CIRCUITPY Without Access to the REPL <https://learn.adafruit.com/welcome-to-circuitpython/troubleshooting#erase-circuitpy-without-access-to-the-repl-3105309-32>`_
section of the Troubleshooting page in the Welcome to CircuitPython guide covers the non-REPL
erase process for various boards. Visit the guide, find the process that applies to your board,
and follow the instructions to erase your board.

ValueError: Incompatible ``.mpy`` file.
---------------------------------------

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 it's 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, 2.x and 3.x, and will change again between 6.x and 7.x.

So, for instance, if you just upgraded to CircuitPython 7.x from 6.x you'll need to download a
newer version of the library that triggered the error on ``import``. They are
all available in the
`Adafruit bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest>`_
and the `Community bundle <https://github.com/adafruit/CircuitPython_Community_Bundle/releases/latest>`_.
Make sure to download a version with 7.0.0 or higher in the filename.