Troubleshooting
A guide to solving common problems.
Navigation
General Troubleshooting Advice
"Have You Tried Turning It Off And On Again?"
- Seriously, restarting your computer can solve a wide variety of problems.
Install the latest version of the Arduino IDE
- The Arduino IDE is continuously being improved. By using an old IDE version you may be missing out on the fix for the bug that's causing your problem.
- Note that you need to get the latest IDE version from https://www.arduino.cc/en/Main/Software, the version of the Arduino IDE available via Linux package managers is very outdated and non-standard.
- Sometimes recent development may introduce new bugs so upgrading does have the potential to confuse the troubleshooting process.
- If you're using Windows and want to have multiple versions of the Arduino IDE installed then use the "Windows ZIP file for non admin install" download link.
Installing the Arduino IDE
Windows 10 is required but I'm using an older version of Windows.
- The Arduino IDE is compatible with Windows versions XP and newer. However, the "Windows app" version of the Arduino IDE does require Windows 10. Please use either the "Windows Installer" or "Windows ZIP file for non admin install" download links at https://www.arduino.cc/en/Main/Software.
The Arduino IDE doesn't start
- Start the Arduino IDE from the command line to get some output that may give helpful clues to the cause of the problem. Windows users should run arduino_debug.exe, found in the root of the Arduino IDE installation folder.
Arduino IDE Editor
The editor window is gray and I can't type anything in it.
- Do this: File > Preferences > Use external editor (uncheck) > OK.
Boards Manager
Compiling
Board x (platform y, package z) is unknown
- (x, y, z being dependent on the board selection)
- This problem is caused by the the Arduino IDE not fully removing the previous hardware package version when you updated to a new version via Boards Manager. It is solved by completely removing the old package version:
- Click the link at the line following File > Preferences > More preferences can be edited directly in the file. This will open the Arduino15 or similar folder.
- Open the packages subfolder. This folder contains a subfolder for each of the vendor names of the hardware packages you have installed via Boards Manager.
- Open the vendor folder of the problematic hardware package.
- Open the hardware subfolder.
- Open the architecture subfolder of the problematic hardware package.
- You will now see multiple version subfolders. One of these folders is the one you upgraded from that was not fully removed. Delete that folder. Please be very careful when deleting files on your computer, when in doubt back up!
Uploading
General
- Make sure it's actually an upload problem. The Arduino IDE compiles your code before uploading so a bug in your code will also cause the upload to fail but that is not considered an upload error. If you do a Sketch > Verify/Compile and get a failure then you need to fix the problems in your code before you have any hope of uploading.
- The first thing to do when you have an upload problem is to do File > Preferences > Show verbose output during: > upload (check) > OK then try uploading again. This will cause useful information about the upload to be displayed in the black console window at the bottom of the Arduino IDE window. Note that the text will likely be longer than can be seen at once in the console window so you need to use the scrollbar on the right side to view it all.
- Make sure you have the right board selected in the Tools > Board menu. Selecting the wrong board could result in a wide range of error messages
- Make sure you have the right port selected in the Tools > Port menu. If this menu is grayed out, see the information on that problem in this troubleshooting guide.
"avrdude: ser_open(): can't open device "\\.\COM1": The system cannot find the file specified."
- Typically this means that you have forgotten to select the port of your Arduino from the Tools > Port menu. If that menu is grayed or the port of your Arduino does not appear on the menu out then see that item in this guide.
The Tools > Port menu is grayed out or the port of my Arduino board doesn't appear in the Tools > Port menu.
- You may need to install the driver for the USB-serial chip on your Arduino. Determine which chip is used on your Arduino and install the driver. The USB-serial chip will usually be near the USB jack on your board or on the bottom of the board in the case of the Nano.
- You may be using a charge-only or defective USB cable. Test your cable on another device to confirm that it works for data.
- Using a USB 3.0 port on your computer may cause problems. Try a USB 2.0 port.
"avrdude: ser_open(): can't open device ...: Access is denied."
- Make sure the port isn't open in Serial Monitor or any other program.
"avrdude: stk500_getsync() attempt 1 of 10: not in sync: resp=..." error when uploading to Nano
- If you have a clone or old official Nano: Select Tools > Processor > ATmega328P (Old Bootloader).
- If you have a new (>=2018) official Nano: Make sure you have Arduino AVR Boards 1.6.21 or newer installed (via Tools > Board > Boards Manager) and select Tools > Processor > ATmega328P.
"the selected serial port avrdude: stk500_send(): failed to send command to serial port" when uploading to ATmega2560 based board such as Arduino Mega.
Does your sketch contain !!! in a string literal? This will cause the issue if your board has an old bootloader version installed. Install the latest version of the Arduino IDE and use an ISP programmer to do a Tools > Burn Bootloader on your board to install a recent version of the bootloader that doesn't have this bug.
"espcomm_sync failed" error when uploading to ESP8266
See https://arduino-esp8266.readthedocs.io/en/latest/faq/readme.html#i-am-getting-espcomm-sync-failed-error-when-trying-to-upload-my-esp-how-to-resolve-this-issue.
Burning Bootloader
"avrdude: warning: cannot set sck period. please check for usbasp firmware update."
- This is normal with the common USBasp clones and does not indicate a problem. If you are having a problem burning the bootloader this is not the cause. It is possible to upgrade the firmware but it's a somewhat advanced project so you should only upgrade if you actually need the features of the new firmware version.
Arduino Web Editor