Troubleshooting
From time to time, you will run into issues when working with CircuitPython. Here are a few things you may encounter and how to resolve them.
Always Run the Latest Version of CircuitPython and Libraries
As CircuitPython development continues and there are new releases, Adafruit will stop supporting older releases. You need to update to the latest CircuitPython.
You need to download the CircuitPython Library Bundle that matches your version of CircuitPython. Please update CircuitPython and then download the latest bundle.
As new versions of CircuitPython are released, Adafruit will stop providing the previous bundles as automatically created downloads on the Adafruit CircuitPython Library Bundle repo. If you must continue to use an earlier version, you can still download the appropriate version of mpy-cross from the particular release of CircuitPython on the CircuitPython repo and create your own compatible .mpy library files. However, it is best to update to the latest for both CircuitPython and the library bundle.
I have to continue using CircuitPython 7.x or earlier. Where can I find compatible libraries?
Adafruit is no longer building or supporting the CircuitPython 7.x or earlier library bundles. You are highly encourged to update CircuitPython to the latest version and use the current version of the libraries. However, if for some reason you cannot update, links to the previous bundles are available in the FAQ.
macOS Sonoma before 14.4: Errors Writing to CIRCUITPY
macOS 14.4 - 15.1: Slow Writes to CIRCUITPY
macOS Sonoma before 14.4 took many seconds to complete writes to small FAT drives, 8MB or smaller. This causes errors when writing to CIRCUITPY. The best solution was to remount the CIRCUITPY drive after it is automatically mounted. Or consider downgrading back to Ventura if that works for you. This problem was tracked in CircuitPython GitHub issue 8449.
Below is a shell script to do this remount conveniently (courtesy @czei in GitHub). Copy the code here into a file named, say, remount-CIRCUITPY.sh. Place the file in a directory on your PATH, or in some other convenient place.
macOS Sonoma 14.4 and versions of macOS before Sequoia 15.2 did not have the problem above, but did take an inordinately long time to write to FAT drives of size 1GB or less (40 times longer than 2GB drives). As of macOS 15.2, writes are no longer very slow. This problem was tracked in CircuitPython GitHub issue 8918.
#!/bin/sh # # This works around bug where, by default, # macOS 14.x before 14.4 writes part of a file immediately, # and then doesn't update the directory for 20-60 seconds, causing # the file system to be corrupted. # disky=`df | grep CIRCUITPY | cut -d" " -f1` sudo umount /Volumes/CIRCUITPY sudo mkdir /Volumes/CIRCUITPY sleep 2 sudo mount -v -o noasync -t msdos $disky /Volumes/CIRCUITPY
Then in a Terminal window, do this to make this script executable:
chmod +x remount-CIRCUITPY.sh
Place the file in a directory on your PATH, or in some other convenient place.
Now, each time you plug in or reset your CIRCUITPY board, run the file remount-CIRCUITPY.sh. You can run it in a Terminal window or you may be able to place it on the desktop or in your dock to run it just by double-clicking.
This will be something of a nuisance but it is the safest solution.
This problem is being tracked in this CircuitPython issue.
Bootloader (boardnameBOOT) Drive Not Present
You may have a different board.
Only Adafruit Express boards and the SAMD21 non-Express boards ship with the UF2 bootloader installed. The Feather M0 Basic, Feather M0 Adalogger, and similar boards use a regular Arduino-compatible bootloader, which does not show a boardnameBOOT drive.
MakeCode
If you are running a MakeCode program on Circuit Playground Express, press the reset button just once to get the CPLAYBOOT drive to show up. Pressing it twice will not work.
macOS
DriveDx and its accompanything SAT SMART Driver can interfere with seeing the BOOT drive. See this forum post for how to fix the problem.
Windows 10 or later
Did you install the Adafruit Windows Drivers package by mistake, or did you upgrade to Windows 10 or later with the driver package installed? You don't need to install this package on Windows 10 or 11for most Adafruit boards. The old version (v1.5) can interfere with recognizing your device. Go to Settings -> Apps and uninstall all the "Adafruit" driver programs.
Windows 7 or 8.1
Windows 7 and 8.1 have reached end of life. It is recommended that you upgrade to Windows 10 or 11 if possible. Drivers are available for some older CircuitPython boards, but there are no plans to release drivers for newer boards.
You should now be done! Test by unplugging and replugging the board. You should see the CIRCUITPY drive, and when you double-click the reset button (single click on Circuit Playground Express running MakeCode), you should see the appropriate boardnameBOOT drive.
Let us know in the Adafruit support forums or on the Adafruit Discord if this does not work for you!
Windows Explorer Locks Up When Accessing boardnameBOOT Drive
On Windows, several third-party programs that can cause issues. The symptom is that you try to access the boardnameBOOT drive, and Windows or Windows Explorer seems to lock up. These programs are known to cause trouble:
- AIDA64: to fix, stop the program. This problem has been reported to AIDA64. They acquired hardware to test, and released a beta version that fixes the problem. This may have been incorporated into the latest release. Please let us know in the forums if you test this.
- BitDefender anti-virus
- Hard Disk Sentinel
- Kaspersky anti-virus: To fix, you may need to disable Kaspersky completely. Disabling some aspects of Kaspersky does not always solve the problem. This problem has been reported to Kaspersky.
- ESET NOD32 anti-virus: There have been problems with at least version 9.0.386.0, solved by uninstallation.
Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied
On Windows, a Western DIgital (WD) utility that comes with their external USB drives can interfere with copying UF2 files to the boardnameBOOT drive. Uninstall that utility to fix the problem.
CIRCUITPY Drive Does Not Appear or Disappears Quickly
BitDefender anti-virus has been reported to block access to CIRCUITPY. You can set an exception for the drive letter.
Kaspersky anti-virus can block the appearance of the CIRCUITPY drive. There has not yet been settings change discovered that prevents this. Complete uninstallation of Kaspersky fixes the problem.
Norton anti-virus can interfere with CIRCUITPY. A user has reported this problem on Windows 7. The user turned off both Smart Firewall and Auto Protect, and CIRCUITPY then appeared.
Sophos Endpoint security software can cause CIRCUITPY to disappear and the BOOT drive to reappear. It is not clear what causes this behavior.
Samsung Magician can cause CIRCUITPY to disappear (reported here and here).
"M105" Seen on Display, Crashes, Missing CIRCUITPY
The Cura 3D printing program sends 3D printing GCODE commands to unused serial ports to try to find 3D printers connected over serial. This causes a variety of problems. Disable (uncheck) USB Printing in Cura in the Market -> Installed menu, or uninstall Cura. For more information see this forum post, this CircuitPython issue, and this Cura issue.
Device Errors or Problems on Windows
Windows can become confused about USB device installations. Try cleaning up your USB devices. Use Uwe Sieber's Device Cleanup Tool (on that page, scroll down to "Device Cleanup Tool"). Download and unzip the tool. Unplug all the boards and other USB devices you want to clean up. Run the tool as Administrator. You will see a listing like this, probably with many more devices. It is listing all the USB devices that are not currently attached.
Select all the devices you want to remove, and then press Delete. It is usually safe just to select everything. Any device that is removed will get a fresh install when you plug it in. Using the Device Cleanup Tool also discards all the COM port assignments for the unplugged boards. If you have used many Arduino and CircuitPython boards, you have probably seen higher and higher COM port numbers used, seemingly without end. This will fix that problem.
Serial Console in Mu Not Displaying Anything
There are times when the serial console will accurately not display anything, such as, when no code is currently running, or when code with no serial output is already running before you open the console. However, if you find yourself in a situation where you feel it should be displaying something like an error, consider the following.
Depending on the size of your screen or Mu window, when you open the serial console, the serial console panel may be very small. This can be a problem. A basic CircuitPython error takes 10 lines to display!
Auto-reload is on. Simply save files over USB to run them or enter REPL to disable. code.py output: Traceback (most recent call last): File "code.py", line 7 SyntaxError: invalid syntax Press any key to enter the REPL. Use CTRL-D to reload.
More complex errors take even more lines!
Therefore, if your serial console panel is five lines tall or less, you may only see blank lines or blank lines followed by Press any key to enter the REPL. Use CTRL-D to reload.. If this is the case, you need to either mouse over the top of the panel to utilise the option to resize the serial panel, or use the scrollbar on the right side to scroll up and find your message.
This applies to any kind of serial output whether it be error messages or print statements. So before you start trying to debug your problem on the hardware side, be sure to check that you haven't simply missed the serial messages due to serial output panel height.
code.py Restarts Constantly
CircuitPython will restart code.py if you or your computer writes to something on the CIRCUITPY drive. This feature is called auto-reload, and lets you test a change to your program immediately.
Some utility programs, such as backup, anti-virus, or disk-checking apps, will write to the CIRCUITPY as part of their operation. Sometimes they do this very frequently, causing constant restarts.
Acronis True Image and related Acronis programs on Windows are known to cause this problem. It is possible to prevent this by disabling the "Acronis Managed Machine Service Mini".
If you cannot stop whatever is causing the writes, you can disable auto-reload by putting this code in boot.py or code.py:
import supervisor supervisor.runtime.autoreload = False
CircuitPython RGB Status Light
Nearly all CircuitPython-capable boards have a single NeoPixel or DotStar RGB LED on the board that indicates the status of CircuitPython. A few boards designed before CircuitPython existed, such as the Feather M0 Basic, do not.
Circuit Playground Express and Circuit Playground Bluefruit have multiple RGB LEDs, but do NOT have a status LED. The LEDs are all green when in the bootloader. In versions before 7.0.0, they do NOT indicate any status while running CircuitPython.
CircuitPython 7.0.0 and Later
The status LED blinks were changed in CircuitPython 7.0.0 in order to save battery power and simplify the blinks. These blink patterns will occur on single color LEDs when the board does not have any RGB LEDs. Speed and blink count also vary for this reason.
On start up, the LED will blink YELLOW multiple times for 1 second. Pressing the RESET button (or on Espressif, the BOOT button) during this time will restart the board and then enter safe mode. On Bluetooth capable boards, after the yellow blinks, there will be a set of faster blue blinks. Pressing reset during the BLUE blinks will clear Bluetooth information and start the device in discoverable mode, so it can be used with a BLE code editor.
Once started, CircuitPython will blink a pattern every 5 seconds when no user code is running to indicate why the code stopped:
- 1 GREEN blink: Code finished without error.
- 2 RED blinks: Code ended due to an exception. Check the serial console for details.
- 3 YELLOW blinks: CircuitPython is in safe mode. No user code was run. Check the serial console for safe mode reason.
When in the REPL, CircuitPython will set the status LED to WHITE. You can change the LED color from the REPL. The status indicator will not persist on non-NeoPixel or DotStar LEDs.
CircuitPython 6.3.0 and earlier
Here's what the colors and blinking mean:
- steady GREEN: code.py (or code.txt, main.py, or main.txt) is running
- pulsing GREEN: code.py (etc.) has finished or does not exist
- steady YELLOW at start up: (4.0.0-alpha.5 and newer) CircuitPython is waiting for a reset to indicate that it should start in safe mode
- pulsing YELLOW: Circuit Python is in safe mode: it crashed and restarted
- steady WHITE: REPL is running
- steady BLUE: boot.py is running
Colors with multiple flashes following indicate a Python exception and then indicate the line number of the error. The color of the first flash indicates the type of error:
- GREEN: IndentationError
- CYAN: SyntaxError
- WHITE: NameError
- ORANGE: OSError
- PURPLE: ValueError
- YELLOW: other error
These are followed by flashes indicating the line number, including place value. WHITE flashes are thousands' place, BLUE are hundreds' place, YELLOW are tens' place, and CYAN are one's place. So for example, an error on line 32 would flash YELLOW three times and then CYAN two times. Zeroes are indicated by an extra-long dark gap.
Serial console showing ValueError: Incompatible .mpy file
This error occurs when importing a module that is stored as a .mpy binary file that was generated by a different version of CircuitPython than the one its being loaded into. In particular, the mpy binary format changed between CircuitPython versions 6.x and 7.x, 2.x and 3.x, and 1.x and 2.x.
So, for instance, if you 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. All libraries are available in the Adafruit bundle.
CIRCUITPY Drive Issues
You may find that you can no longer save files to your CIRCUITPY drive. You may find that your CIRCUITPY stops showing up in your file explorer, or shows up as NO_NAME. These are indicators that your filesystem has issues. When the CIRCUITPY disk is not safely ejected before being reset by the button or being disconnected from USB, it may corrupt the flash drive. It can happen on Windows, Mac or Linux, though it is more common on Windows.
Be aware, if you have used Arduino to program your board, CircuitPython is no longer able to provide the USB services. You will need to reload CircuitPython to resolve this situation.
The easiest first step is to reload CircuitPython. Double-tap reset on the board so you get a boardnameBOOT drive rather than a CIRCUITPY drive, and copy the latest version of CircuitPython (.uf2) back to the board. This may restore CIRCUITPY functionality.
If reloading CircuitPython does not resolve your issue, the next step is to try putting the board into safe mode.
Safe Mode
Whether you've run into a situation where you can no longer edit your code.py on your CIRCUITPY drive, your board has gotten into a state where CIRCUITPY is read-only, or you have turned off the CIRCUITPY drive altogether, safe mode can help.
Safe mode in CircuitPython does not run any user code on startup, and disables auto-reload. This means a few things. First, safe mode bypasses any code in boot.py (where you can set CIRCUITPY read-only or turn it off completely). Second, it does not run the code in code.py. And finally, it does not automatically soft-reload when data is written to the CIRCUITPY drive.
Therefore, whatever you may have done to put your board in a non-interactive state, safe mode gives you the opportunity to correct it without losing all of the data on the CIRCUITPY drive.
Entering Safe Mode in CircuitPython 7.x and Later
You can enter safe by pressing reset during the right time when the board boots. Immediately after the board starts up or resets, it waits one second. On some boards, the onboard status LED will blink yellow during that time. If you press reset during that one second period, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a "slow" double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)
Entering Safe Mode in CircuitPython 6.x
You can enter safe by pressing reset during the right time when the board boots.. Immediately after the board starts up or resets, it waits 0.7 seconds. On some boards, the onboard status LED (highlighted in green above) will turn solid yellow during this time. If you press reset during that 0.7 seconds, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a slow double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)
In Safe Mode
Once you've entered safe mode successfully in CircuitPython 6.x, the LED will pulse yellow.
If you successfully enter safe mode on CircuitPython 7.x, the LED will intermittently blink yellow three times.
If you connect to the serial console, you'll find the following message.
Auto-reload is off. Running in safe mode! Not running saved code. CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode. Press any key to enter the REPL. Use CTRL-D to reload.
You can now edit the contents of the CIRCUITPY drive. Remember, your code will not run until you press the reset button, or unplug and plug in your board, to get out of safe mode.
At this point, you'll want to remove any user code in code.py and, if present, the boot.py file from CIRCUITPY. Once removed, tap the reset button, or unplug and plug in your board, to restart CircuitPython. This will restart the board and may resolve your drive issues. If resolved, you can begin coding again as usual.
If safe mode does not resolve your issue, the board must be completely erased and CircuitPython must be reloaded onto the board.
To erase CIRCUITPY: storage.erase_filesystem()
CircuitPython includes a built-in function to erase and reformat the filesystem. If you have a version of CircuitPython older than 2.3.0 on your board, you can update to the newest version to do this.
- Connect to the CircuitPython REPL using Mu or a terminal program.
- Type the following into the REPL:
>>> import storage >>> storage.erase_filesystem()
CIRCUITPY will be erased and reformatted, and your board will restart. That's it!
Erase CIRCUITPY Without Access to the REPL
If you can't access the REPL, or you're running a version of CircuitPython previous to 2.3.0 and you don't want to upgrade, there are options available for some specific boards.
The options listed below are considered to be the "old way" of erasing your board. The method shown above using the REPL is highly recommended as the best method for erasing your board.
For the specific boards listed below:
If the board you are trying to erase is listed below, follow the steps to use the file to erase your board.
1. Download the correct erase file:
2. Double-click the reset button on the board to bring up the boardnameBOOT drive.
3. Drag the erase .uf2 file to the boardnameBOOT drive.
4. The status LED will turn yellow or blue, indicating the erase has started.
5. After approximately 15 seconds, the status LED will light up green. On the NeoTrellis M4 this is the first NeoPixel on the grid
6. Double-click the reset button on the board to bring up the boardnameBOOT drive.
7. Drag the appropriate latest release of CircuitPython .uf2 file to the boardnameBOOT drive.
It should reboot automatically and you should see CIRCUITPY in your file explorer again.
If the LED flashes red during step 5, it means the erase has failed. Repeat the steps starting with 2.
If you haven't already downloaded the latest release of CircuitPython for your board, check out the installation page. You'll also need to load your code and reinstall your libraries!
For SAMD21 non-Express boards that have a UF2 bootloader:
Any SAMD21-based microcontroller that does not have external flash available is considered a SAMD21 non-Express board. Non-Express boards that have a UF2 bootloader include Trinket M0, GEMMA M0, QT Py M0, and the SAMD21-based Trinkey boards.
If you are trying to erase a SAMD21 non-Express board, follow these steps to erase your board.
1. Download the erase file:
2. Double-click the reset button on the board to bring up the boardnameBOOT drive.
3. Drag the erase .uf2 file to the boardnameBOOT drive.
4. The boot LED will start flashing again, and the boardnameBOOT drive will reappear.
5. Drag the appropriate latest release CircuitPython .uf2 file to the boardnameBOOT drive.
It should reboot automatically and you should see CIRCUITPY in your file explorer again.
If you haven't already downloaded the latest release of CircuitPython for your board, check out the installation page YYou'll also need to load your code and reinstall your libraries!
For SAMD21 non-Express boards that do not have a UF2 bootloader:
Any SAMD21-based microcontroller that does not have external flash available is considered a SAMD21 non-Express board. Non-Express boards that do not have a UF2 bootloader include the Feather M0 Basic Proto, Feather Adalogger, or the Arduino Zero.
If you are trying to erase a non-Express board that does not have a UF2 bootloader, follow these directions to reload CircuitPython using bossac, which will erase and re-create CIRCUITPY.
Running Out of File Space on SAMD21 Non-Express Boards
Any SAMD21-based microcontroller that does not have external flash available is considered a SAMD21 non-Express board. This includes boards like the Trinket M0, GEMMA M0, QT Py M0, and the SAMD21-based Trinkey boards.
The file system on the board is very tiny. (Smaller than an ancient floppy disk.) So, its likely you'll run out of space but don't panic! There are a number of ways to free up space.
Delete something!
The simplest way of freeing up space is to delete files from the drive. Perhaps there are libraries in the lib folder that you aren't using anymore or test code that isn't in use. Don't delete the lib folder completely, though, just remove what you don't need.
The board ships with the Windows 7 serial driver too! Feel free to delete that if you don't need it or have already installed it. It's ~12KiB or so.
Use tabs
One unique feature of Python is that the indentation of code matters. Usually the recommendation is to indent code with four spaces for every indent. In general, that is recommended too. However, one trick to storing more human-readable code is to use a single tab character for indentation. This approach uses 1/4 of the space for indentation and can be significant when you're counting bytes.
On macOS?
MacOS loves to generate hidden files. Luckily you can disable some of the extra hidden files that macOS adds by running a few commands to disable search indexing and create zero byte placeholders. Follow the steps below to maximize the amount of space available on macOS.
Prevent & Remove macOS Hidden Files
First find the volume name for your board. With the board plugged in run this command in a terminal to list all the volumes:
ls -l /Volumes
Look for a volume with a name like CIRCUITPY (the default for CircuitPython). The full path to the volume is the /Volumes/CIRCUITPY path.
Now follow the steps from this question to run these terminal commands that stop hidden files from being created on the board:
mdutil -i off /Volumes/CIRCUITPY
cd /Volumes/CIRCUITPY
rm -rf .{,_.}{fseventsd,Spotlight-V*,Trashes}
mkdir .fseventsd
touch .fseventsd/no_log .metadata_never_index .Trashes
cd -
Replace /Volumes/CIRCUITPY in the commands above with the full path to your board's volume if it's different. At this point all the hidden files should be cleared from the board and some hidden files will be prevented from being created.
Alternatively, with CircuitPython 4.x and above, the special files and folders mentioned above will be created automatically if you erase and reformat the filesystem. WARNING: Save your files first! Do this in the REPL:
>>> import storage>>> storage.erase_filesystem()
However there are still some cases where hidden files will be created by MacOS. In particular if you copy a file that was downloaded from the internet it will have special metadata that MacOS stores as a hidden file. Luckily you can run a copy command from the terminal to copy files without this hidden metadata file. See the steps below.
Copy Files on macOS Without Creating Hidden Files
Once you've disabled and removed hidden files with the above commands on macOS you need to be careful to copy files to the board with a special command that prevents future hidden files from being created. Unfortunately you cannot use drag and drop copy in Finder because it will still create these hidden extended attribute files in some cases (for files downloaded from the internet, like Adafruit's modules).
To copy a file or folder use the -X option for the cp command in a terminal. For example to copy a file_name.mpy file to the board use a command like:
cp -X file_name.mpy /Volumes/CIRCUITPY
(Replace file_name.mpy with the name of the file you want to copy.)
Or to copy a folder and all of the files and folders contained within, use a command like:
cp -rX folder_to_copy /Volumes/CIRCUITPY
If you are copying to the lib folder, or another folder, make sure it exists before copying.
# if lib does not exist, you'll create a file named lib ! cp -X file_name.mpy /Volumes/CIRCUITPY/lib # This is safer, and will complain if a lib folder does not exist. cp -X file_name.mpy /Volumes/CIRCUITPY/lib/
Other macOS Space-Saving Tips
If you'd like to see the amount of space used on the drive and manually delete hidden files here's how to do so. First, move into the Volumes/ directory with cd /Volumes/, and then list the amount of space used on the CIRCUITPY drive with the df command.
That's not very much space left! The next step is to show a list of the files currently on the CIRCUITPY drive, including the hidden files, using the ls command. You cannot use Finder to do this, you must do it via command line!
There are a few of the hidden files that MacOS loves to generate, all of which begin with a ._ before the file name. Remove the ._ files using the rm command. You can remove them all once by running rm CIRCUITPY/._*. The * acts as a wildcard to apply the command to everything that begins with ._ at the same time.
Finally, you can run df again to see the current space used.
Nice! You have 12Ki more than before! This space can now be used for libraries and code!
Device Locked Up or Boot Looping
In rare cases, it may happen that something in your code.py or boot.py files causes the device to get locked up, or even go into a boot loop. A boot loop occurs when the board reboots repeatedly and never fully loads. These are not caused by your everyday Python exceptions, typically it's the result of a deeper problem within CircuitPython. In this situation, it can be difficult to recover your device if CIRCUITPY is not allowing you to modify the code.py or boot.py files. Safe mode is one recovery option. When the device boots up in safe mode it will not run the code.py or boot.py scripts, but will still connect the CIRCUITPY drive so that you can remove or modify those files as needed.
For more information on safe mode and how to enter safe mode, see the Safe Mode section on this page.
Page last edited January 13, 2025
Text editor powered by tinymce.
