Arduino Troubleshooting

Why I can't upload my programs to the Arduino board?

Ardunio suggests...
... that you check on components such as your Arduino Software, your drivers, access to the serial port, physical connection, auto-reset capabilities, and bootloader. They also have a Support Forum if none of their steps for checking these components help you upload.

Why do I get "Build folder disappeared or could not be written" on Mac OS X?

Arduino wants to know...
Did you drag the Arduino.app out of the disk image (and into, say, your Applications folder)? If not, you won't be able to upload the examples.

Why doesn't the Arduino software run after I updated the Java on my Mac?

Your Arduino needs a little guidance...
The latest Java update from Apple attempts to use 64-bit version of native libraries, but the Arduino application comes with a 32 bit version of the RXTX library. If you launch Arduino, you'll get an error like:

Uncaught exception in main method: java.lang.UnsatisfiedLinkError: /Applications/arduino-0016/Arduino 16.app/Contents/Resources/Java/librxtxSerial.jnilib: no suitable image found. Did find: /Applications/arduino-0016/Arduino 16.app/Contents/Resources/Java/librxtxSerial.jnilib: no matching architecture in universal wrapper

To fix this, click on the Arduino application (e.g. Arduino 16.app) in Finder, and select Get Info from the File menu. In the info panel, click the Open in 32 Bit Mode checkbox. You should then be able to launch Arduino normally.

Why do I get a java.lang.StackOverflowError when I try to compile my program?

Arduino sometimes gets confused by text strings...
The Arduino environment does some preliminary processing on your sketch by manipulating the code using regular expressions. This sometimes gets confused by certain strings of text. If you see an error like:

java.lang.StackOverflowError

at java.util.Vector.addElement(Unknown Source)

at java.util.Stack.push(Unknown Source)

at com.oroinc.text.regex.Perl5Matcher._pushState(Perl5Matcher.java)

or:

at com.oroinc.text.regex.Perl5Matcher._match(Perl5Matcher.java)

this is what's happening. Look for unusual sequences involving "double-quotes", "single-quotes", \ backslashes, comments, etc. For example, missing quotes can cause problems and so can the sequence ' \ "' (use '"' instead).

What type of power supply should I use with my Arduino board?

Arduino has a more in-depth explanation...
... but the gist is that USB power is satisfactory, though there are AC power options available, if you find you need more power. It is always best to check the specs for your specific Arduino and those for the device you are using to supply power to it.

Why doesn't my sketch start when I'm powering the board with an external power supply? (Arduino Diecimila or earlier)

Your Arduino is just trying to protect itself...
Because the RX pin is unconnected, the bootloader on the board may be seeing garbage data coming in, meaning that it never times out and starts your sketch. Try tying the RX pin to ground with a 10K resistor (or connecting RX directly to the TX pin).

Why does the Arduino software freeze when I try to upload a program? (on Windows)?

Your Arduino might be fighting with another process...
This might be caused by a conflict with the Logitech process 'LVPrcSrv.exe'. Open the Task Manager and see if this program is running, and if so, kill it before attempting the upload. more information

What if my board doesn't turn on (the green power LED doesn't light up)?

Your Arduino may not be configured correctly...
If you're using a Diecimila or older USB board (e.g. NG), make sure that the jumper (little plastic piece near the USB plug) is on the correct pins. If you're powering the board with an external power supply (plugged into the power plug), the jumper should be on the two pins closest to the power plug. If you're powering the board through the USB, the jumper should be on the two pins closest to the USB plug.

Why does my Diecimila take such a long time (6-8 seconds) to start my sketch?

Your Arduino may not have the correct bootloader...
Some of the Arduino Diecimila boards were accidentally burned with the Arduino NG bootloader. It should work fine, but has a longer delay when the board is reset (because the NG doesn't have an automatic reset, so you have to time the uploads manually). You can recognize the NG bootloader because the LED on pin 13 will blink three times when you reset the board (as compared to once with the Diecimila bootloader). If your Diecimila has the NG bootloader on it, you may need to physically press the reset button on the board before uploading your sketch. You can also burn the correct bootloader onto your Diecimila, see the bootloader page for details.

What should I do if I get an error when launching arduino.exe on Windows?

Your Arduino may need a manual start...
If you get an error when double-clicking the arduino.exe executable on Windows, for example:

Arduino has encountered a problem and needs to close.

you'll need to launch Arduino using the run.bat file. Please be patient, the Arduino environment may take some time to open.

Why won't Arduino run on old versions of Mac OS X?

Your Arduino might not like your libraries...
If you get an error like this:

Link (dyld) error:

dyld: /Applications/arduino-0004/Arduino 04.app/Contents/MacOS/Arduino Undefined symbols:

/Applications/arduino-0004/librxtxSerial.jnilib undefined reference to _printf$LDBL128 expected to be defined in /usr/lib/libSystem.B.dylib

you probably need to upgrade to Max OS X 10.3.9 or later. Older versions have incompatible versions of some system libraries.

What do I do if I get an UnsatisfiedLinkError error (about native library librxtxSerial.jnilib) when launching Arduino?

Your Arduino probably found an old communicatons library file...
If you get an error like this when launching Arduino:

Uncaught exception in main method: java.lang.UnsatisfiedLinkError: Native Library /Users/anu/Desktop/arduino-0002/librxtxSerial.jnilib already loaded in another classloader

you probably have an old version of the communications library lying around. Search for comm.jar or jcl.jar in /System/Library/Frameworks/JavaVM.framework/ or in directories in your CLASSPATH or PATH environment variables.

What about the error "Could not find the main class."?

Your Arduino might not understand the way you extracted the contents of the .zip file...
If you get this error when launching Arduino:

Java Virtual Machine Launcher: Could not find the main class. Program will exit.

make sure that you correctly extracted the contents of the Arduino .zip file - in particular that the lib directory is directly inside of the Arduino directory and contains the file pde.jar.

What can I do about cygwin conflicts on Windows?

Your Arduino might have found cygwin to already be running...
If you already have cygwin installed on your machine, you might get an error like this when you try to compile a sketch in Arduino:

6 [main] ? (3512) C:\Dev\arduino-0006\tools\avr\bin\avr-gcc.exe: *** fatal error - C:\Dev\arduino-0006\tools\avr\bin\avr-gcc.exe: *** system shared memory version mismatch detected - 0x75BE0084/0x75BE009C.

This problem is probably due to using incompatible versions of the cygwin DLL.

Search for cygwin1.dll using the Windows Start->Find/Search facility and delete all but the most recent version. The most recent version should reside in x:\cygwin\bin, where 'x' is the drive on which you have installed the cygwin distribution. Rebooting is also suggested if you are unable to find another cygwin DLL. If so, first make sure that you don't have cygwin running when you use Arduino. If that doesn't help, you can try deleting cygwin1.dll from the Arduino directory and replacing it with the cygwin1.dll from your existing cygwin install (probably in c:\cygwin\bin).

Why does do the Arduino software and the Tools menu take a long time to open (on Windows)?

Your Arduino might be fighting with another device...
If the Arduino software takes a long time to start up and appears to freeze when you try to open the Tools menu, there by a conflict with another device on your system. The Arduino software, on startup and when you open the Tools menu, tries to get a list of all the COM ports on your computer. It's possible that a COM port created by one of the devices on your computer slows down this process. Take a look in the Device Manager. Try disabling the devices that provide COM ports (e.g. Bluetooth devices).

Why doesn't my board show in the Tools | Serial Port menu?

Arduino has a few ideas as to why this might be happening and the steps you can take to remedy it...

What if I get a gnu.io.PortInUseException when uploading code or using the serial monitor (on the Mac)?

Another application might have stollen your Arduino's seat (port)...

Error inside Serial.<init>()

gnu.io.PortInUseException: Unknown Application

at gnu.io.CommPortIdentifier.open(CommPortIdentifier.java:354)

at processing.app.Serial.<init>(Serial.java:127)

at processing.app.Serial.<init>(Serial.java:72)

This probably means that the port is actually in use by another application. Please make sure that you're not running other programs that access serial or USB ports, like PDA sync application, bluetooth device managers, certain firewalls, etc. Also, note that some programs (e.g. Max/MSP) keep the serial port open even when not using it - you may to need to close any patches that use the serial port or quit the application entirely.

If you get this error with Arduino 0004 or earlier, or with Processing, you'll need to run the macosx_setup.command, and then restart your computer. Arduino 0004 includes a modified version of this script that all users need to run (even those who ran the one that came with Arduino 0003). You may also need to delete the contents of the /var/spool/uucp directory.

I'm having trouble with the FTDI USB drivers.

It's probably something with FTDI, not your Arduino...
Try installing the latest drivers from FTDI or contacting their support at support1@ftdichip.com.

Why doesn't my sketch start when I power up or reset the Arduino board?

You're trying to talk to your Arduino before it's had its coffee...
Most likely because you are sending serial data to the board when it firsts turns on. During the first few seconds, the bootloader (a program pre-burned onto the chip on the board) listens for the computer to send it a new sketch to be uploaded to the board. After a few seconds without communication, the bootloader will time out and start the sketch that's already on the board. If you continue to send data to the bootloader, it will never time out and your sketch will never start. You'll either need to find a way to stop serial data from arriving for the first few seconds when the board powers (e.g. by enabling the chip that sends the data from within your setup() function) or burn your sketch onto the board with an external programmer, replacing the bootloader.

Why does my sketch appear to upload successfully but not do anything?

Arduino has a few ideas as to why this might be happening and the steps you can take to remedy it...

How can I reduce the size of my sketch?

Arduino has a few helpful tips and tricks...
The ATmega168 chip on the Arduino board is cheap, but it has only 16 Kb of program code, which isn't very much (and 2 Kb is used by the bootloader).

If you're using floating point, try to rewrite your code with integer math, which should save you about 2 Kb. Delete any #include statements at the top of your sketch for libraries that you're not using.

Otherwise, see if you can make your program shorter.

Why don't I get a PWM (an analog output) when I call analogWrite() on pins other than 3, 5, 6, 9, 10, or 11?

You might be using a pin on your Arduino that doesn't support analog outputs...
The microcontroller on the Arduino board (the ATmega168) only supports PWM/analogWrite() on certain pins. Calling analogWrite() on any other pins will give high (5 volts) for values greater than 128 and low (0 volts) for values less than 128. (Older Arduino boards with an ATmega8 only support PWM output on pins 9, 10, and 11.)

Why do I get errors about undeclared functions or undeclared types?

Your Arduino doesn't like your fancy types/names...
The Arduino environment attempts to automatically generate prototypes for your functions, so that you can order them as you like in your sketch. This process, however, isn't perfect, and sometimes leads to obscure error messages.

If you declare a custom type in your code and create a function that accepts or returns a value of that type, you'll get an error when you try to compile the sketch. This is because the automatically-generated prototype for that function will appear above the type definition.

If you declare a function with a two-word return type (e.g. "unsigned int") the environment will not realize it's a function and will not create a prototype for it. That means you need to provide your own, or place the definition of the function above any calls to it.

Why do I get errors about an invalid device signature when trying to upload a sketch?

There is a bit of a mismatch somewhere with your Arduino...
If you get an error like:

avrdude: Yikes! Invalid device signature.

Double check connections and try again, or use -F to override this check.

it can mean one of two things. Either you have the wrong board selected from the Tools > Board menu or you're not using the right version of avrdude. Arduino uses a slightly modified version of avrdude to upload sketches to the Arduino board. The standard version queries for the board's device signature in a way not understood by the bootloader, resulting in this error. Make sure you're using the version of avrdude that comes with Arduino.

The text of the Arduino getting started guide is licensed under a Creative Commons Attribution-ShareAlike 3.0 License. Code samples in the guide are released into the public domain.