Troubleshooting

From Processing

Having a problem? Hopefully the information on this page will help.

I've found a bug!

I know you're excited, but please avoid the urge to just e-mail us! especially sending mail to Ben or Casey directly. This includes sending us "Personal Messages" on the Discourse section of the site (we have to ignore these, sorry). While you may prefer the privacy of a personal message, it's much quicker for you to write to the board, where you'll find all sorts of helpful people who are also often at all hours of the night. If you e-mail us directly, we'll either not respond or just ask you to use the Discourse board anyway.

We spend a lot of our time helping people with Processing, so reading and following these instructions means that you respect our time and don't want to waste it.

First, read through this page and maybe the Supported Platforms page too in case it's something specific to your operating system (or your Java installation).

Second, search the bug database to see if your problem has already been reported. Most often, this will contain background on the problem, a workaround, or hopefully a bit about its status. The bugs database is unfortunately incomplete so it doesn't cover everything, but it will get better with time.

If you don't find your bug, enter it as a new bug in the database, this will help us keep track of the issue.

When reporting please include information about

1. the revision number (i.e. 1.5.1)
2. the operating system you're using (Windows, Mac, Linux, etc.), and on what kind of hardware
3. a copy of the smallest possible piece of code that will produce the error you're having trouble with
4. details of the error, either the red spew that you see in the console, or the last few lines from the files stdout.txt or stderr.txt from the 'lib' folder.

For stranger errors during compile time, you can also look inside the build folder which contains an intermediate (translated into Java) version of your code. The build folder will be located inside a temporary directory on your machine, probably /tmp/buildNNNN on Mac OS X and Linux, or on Windows, in one of its many "TEMP" folders, inside a buildNNNN folder (the Ns will be numbers or letters). The more details you can post, the better, because it helps us figure out what's going on. Useful things when reporting:

• We want the minimum amount of code that will still replicate the bug. The worst that can happen is we get a report with a subject saying "problem!" along with a three page program. Sure, everyone likes a puzzle, but simpler code will receive a faster response.
• Occasionally we may need you to pack up a copy of your sketch folder or something similar so that we can try and replicate the weirdness on our own machine. Rest assured, we have no interest in messing with your fancy creations or stealing your ideas. The Processing team is a pair of straight-laced boys who hail from the midwestern U.S. who were brought up better than that. And as we often lack enough time to build our own projects, we have even less time to spend figuring out other peoples' projects to rip them off.

Processing won't start! Nothing (or something strange) happens when I click “Run”!

Windows

• Try deleting your preferences file. On Windows XP this is located in Documents and Settings → username → Application Data → Processing → preferences.txt. On Windows 7 (or Vista), it's in Users → username → AppData → Roaming → Processing → preferences.txt. Sometimes a bad preferences file can prevent the application from running. If you've recently hand-edited preferences.txt, that's also a likely suspect. Only delete the preferences file when Processing is not running. And do not modify the preferences.txt file inside the Processing "lib" folder.

• Next try running from a command prompt with the following:

  .\processing.exe --l4j-debug

  This will create a launch4j.log file which will describe what's happening during the startup. Then you can post on the discourse section of the site to inquire for help, or the bugs database if you think it's a bug.

• An exceptionally large sketchbook folder (especially on a slower machine/disk) can sometimes cause startup problems. The launcher starts, but times out because it assumes something is broken (the Processing code is still indexing the sketchbook) and says there's a launch4j error.

• Some graphics cards have conflicts with Java applications and therefore Processing, which can cause the application to hang or freeze. Under one scenario, disabling anti-aliasing on the card will get rid of these problems (Bug 232).

• If you're still having trouble, try disabling any overly protective virus scanning software. It might be holding things up, especially when libraries have been imported.

Mac OS X

• Processing requires Mac OS X 10.6 or later, see the Supported Platforms page for more information.

• First be sure that you're not trying to run Processing from the disk image. As with most programs, Processing needs to be copied to the Applications folder in order for it to run properly.

• If it's still not working, open Console.app, found in Applications → Utilities → Console.app and see if there are any messages. If you don't know what they mean, post them to the forum where someone can help you out.

• A very slow file menu can mean that you have too many sketches in your sketchbook. This is unfortunately not something we can fix because it's happening at the OS level. (Isssue 1202)

• OpenGL sketches on Mac OS X will print an error message upon starting (or when changing the smooth level with smooth()/noSmooth()) that looks like:

2012-03-27 16:25:12.317 java[5741:1707] invalid drawable. 

This is an issue with Apple's Java plugin which seems to have no effect.

• As of a recent (2012) update, Apple's joyless Java implementation now reports

java[15074] <Error>: CGContextGetCTM: invalid context 0x0
java[15074] <Error>: CGContextSetBaseCTM: invalid context 0x0

several times when using Processing, starting a sketch, etc. It appears to be an Apple bug that arrived with a recent Java update or the OS X 10.7.4 update. This is not something that we can fix, and if your sketch isn't working, it has nothing to do with these messages. Because this is so frequently thought to be a Processing bug, or a source of anything wrong in one's sketch, the messages will be hidden starting with Processing 2.0 alpha 7.

• Using developer pre-releases of Java from Apple or Oracle is strongly discouraged. These will usually cause problems and we can't possibly support them.

• Do not use Oracle's Java 7 with Processing. It has not been tested, several things are probably broken, and it may even be slower. Please just use the Java 6 (automatic download) from Apple.

Linux

See the Linux section of Supported Platforms for additional notes.

Any Platform

• Errors inside code that is outside of setup() or draw() may just hang/freeze Processing. For instance, with this code, if "blah.vlw" is not in the "data" folder, it may just hang (and won't work in any case). Never use loadXxxx() methods outside setup() and draw().

PFont font = loadFont("blah.vlw");
 
void setup {
  // your awesome code
}

This used to work and now it doesn't

Read the Changes section of the reference.

Export and Browser Troubles

As of 2.0 alpha 7, we're starting to remove support for applets, in part because of some of the issues below. See the Changes section for more details, and this section will be removed soon.

Sketches (applets) often have trouble once exported that will cause errors in a browser.

To figure out what your problem is, you should first check the Java (not JavaScript!) console. On Windows, right-click the coffee cup at the right of the task bar, and select "Open Console". On Mac OS X, go to Applications → Utilities → Console.app and see what the last few error messages were.

Flicker

Approaching 2011, Java support in most browsers (and on Mac OS X) went into serious decline. Browser makers have been going backwards in their support for Java applets, so high-framerate work like Processing has become almost unusable in many cases. The result is a self-fulfilling "Java sucks in the browser" argument. It's especially pronounced on 64-bit versions of browsers.

With the Processing 2.0 release, and Apple's most recent Java update, we'll have some of these issues fixed, but we're really, really getting screwed by the browser makers, most of whom hate Java applets and are disinclined to make fixes. You can also see the issues in non-Processing Java applets that use animations with a high framerate or a lot of interactivity. (Lower framerate, non-continuous animations, and others have less trouble.)

If you're experiencing flicker in your browser, look at some older examples of Processing work that was completely flicker-free on machines that were 10x slower and underpowered. If those sketches work properly, and a more recent sketch does not, please file a bug. Otherwise, it's something that's quite out of our control.

Security Issues

Security issues are frequent went exporting to the web. Java applets aren't allowed to do things like the following:

• Applets cannot open or write to files on the local machine. So things like saveFrame() will cause an error when run from an applet. To read files, make sure that you use "Add File..." to add the file to your sketch (or place it in the data folder yourself) so that it will be included when exported. Then, only use functions like loadStrings(), loadImage(), openStream(), etc. to read data from your file.

• Applets may not connect to servers other than the one from which they came. If you need to redirect things from another server, you can write a short script that will do it, understanding the possible security consequences for your own machine.

• Applets are also not allowed to do things like capture video or audio. You don't want a malicious applet that turns on your webcam and starts sending things back to their server.

Other Common Problems

• Another common problem is placing images or files into the sketch folder by hand, rather than placing them in the data folder (or using "Add File..." to do so automatically). This will work from the PDE, but on export, the files won't be in included with your sketch because they're not in the data folder.

• Watch out for issues with capitalization! Windows and Mac OS don't care about capitalization, so "blah.JPG" looks just the same as "blah.jpg". However, since most servers run on Unix, capitalization becomes a huge problem, because it must be exact. We've added some checks to try and catch this (at least for images) but they're not perfect. This can especially be a problem when the .JPG extension is not even visible (the default on Windows), so you don't know whether it's upper or lower case.

• Your browser may be using an old version of an applet. Unfortunately it's often difficult to get your browser to flush its cache. You may need to quit all instances of the browser, use alt-reload (or ctrl or shift or option, who knows) to get the new version to show up. On Windows, clicking the Java coffee cup at the right of the task bar can bring up a control panel that will let you flush the Java cache too. This is different across all platforms, but if someone wants to write a good explanation for any platform they're familiar with, please post on the forum area of the site and we'll add it to the FAQ.

Libraries

Some libraries simply don't work with the Web (at least not for now):

• You cannot use the OpenGL library from the Web.(Bug 166) As of revision 0113, it's possible for applets that use the OPENGL renderer setting to run from the Web. As of the 2.0 alpha releases, JOGL support is very up and down, and it's not clear if the final version of 2.0 will support OpenGL applets or not.

• The video library (both Capture and Movie) cannot be used on the Web. As of release 0115, it's possible to play back movies via the Web, however you still cannot capture video without a signed applet (see above).

Out Of Memory Errors (java.lang.OutOfMemoryError)

If you get a OutOfMemoryError while running your program, use the Preferences window to increase the amount of available memory. Check the box next to "Increase maximum available memory" and enter an amount.

Depending on your OS and available RAM, there are limits on how much memory you can ask for.

32-bit operating systems and software are usually limited to addressing somewhere around either 2GB and 4GB of RAM at a time. This means that even if you have 8GB of RAM installed in your machine, you may only be able to use shy of 2GB per application. Most Windows systems seem to be limited to 2 or 3GB, while Mac OS X and Linux can usually access shy of 4GB. Upcoming 64-bit operating systems get around this restriction and increase the amount of available memory significantly. However, even if you're running a 64-bit OS like Mac OS 10.5, or a 64-bit Linux, a combination of factors (version of Java, etc.) may mean that you're still limited by the 32-bit boundary of 2GB or 4GB.

Use this preference with caution, because if you set the memory too high, programs will no longer run in Processing. When you hit run, you'll get error messages.

If this message appears after you hit Run, then you're trying to use more memory than the machine has installed:

Error occurred during initialization of VM
Could not reserve enough space for object heap

The following messages mean that you're trying to use more memory than the Operating System allows (regardless of how much RAM you have):

Invalid maximum heap size: -Xmx5000m
Could not create the Java virtual machine.

Invalid maximum heap size: -Xmx5g
The specified size exceeds the maximum representable size.
Could not create the Java virtual machine.

On Windows with 1G of RAM, the limit seems to be in the neighborhood of 1.5GB. Mac OS X and Linux seem to allow up to just shy of 4GB, depending on how much RAM you have installed. Usually you can allocate almost 50% more RAM than you have installed. i.e. for a machine with 1 GB of physical memory, about 1.5GB is the maximum that can be used. Your mileage will also vary with different versions of Java (1.3, 1.4, 1.5, 1.6...) and your operating system.

On the other hand, Java on Windows XP, for instance, cannot address more than 2GB properly. So with OS and JVM overhead, the total possible memory available is in the neighborhood of 1.5GB (no matter how much RAM you have).

Unfortunately the memory limitations of Java set an upper bound that is outside our control. If you're having trouble creating very large images for this reason, you might look into the PDF or DXF libraries that are included with Processing, or the contributed Illustrator or SVG vector export libraries that can be found on the libraries page as another alternative for creating large format images.

Memory is like any constraint found in other media, you simply need to be more clever about how to deal with the limitations.

To check the amount of memory that's used so far, or how much is available, use Java's Runtime object:

// The amount of memory allocated so far (usually the -Xms setting)
long allocated = Runtime.getRuntime().totalMemory();

// Free memory out of the amount allocated (value above minus used)
long free = Runtime.getRuntime().freeMemory();

// The maximum amount of memory that can eventually be consumed
// by this application. This is the value set by the Preferences
// dialog box to increase the memory settings for an application.
long maximum = Runtime.getRuntime().maxMemory();

There are also some known bugs that eat memory that can be found in the bugs database.

Why don't these Strings equal?

Comparing a string (quoted text) is different in Processing (Java) than it is in ActionScript or some other languages, which often confuses people. For instance, while this might make sense:

String[] lines = loadStrings("sometext.txt");
for (int i = 0; i < lines.length; i++) {
  if (lines[i] == "hello") { 
    println("hello found on line: " + i); // you'll never see this
  }
}

You'll never see the message, even if "hello" is in the list. This is because a String is an object in Java, comparing them with == will only compare whether the two things are pointing at the same memory, not their actual contents. Instead, use equals() or one of the other String methods (eg. equalsIgnoreCase):

String[] lines = loadStrings("sometext.txt");
for (int i = 0; i < lines.length; i++) {
  if (lines[i].equals("hello")) {
    println("hello found on line: " + i); // happiness
  }
}

"But if I write the following code, it works!"

final String HELLO = "Hello";
String hello = "Hello";
println(hello == HELLO);

That's because Java compiler detects two identical constant strings, so it groups them together, and their references (memory location) are identical. If you write instead:

final String HELLO = "Hello";
String hell = "Hell";
println(hell + "o" == HELLO);

It no longer works. Same for strings coming from an external source (file, Internet, etc.).

Why does 2 / 5 = 0 instead of 0.4?

The result of dividing two integers will always be another integer:

int a = 2;
int b = 5;
int result = a / b;
// result is zero

While somewhat confusing at first, this is later useful for more advanced programming.

To get fractions, use a 'float' instead:

float a = 2.0;
float b = 5.0;
float result = a / b;
// 'result' will be 0.4

It is not enough to just divide two integers and set them to a float:

 float y = 2 / 5;

In this case, integer 2 is divided by 5, which is zero, and then zero is assigned to a float. The number doesn't become a float until the left hand side of the = sign. On the other hand, this:

float y = 2.0 / 5;

will work just fine. In this case, Java sees that 2.0 is a float, so it also converts the 5 to a float so that they can be divided, which makes it identical to:

float y = 2.0 / 5.0;

and because floats are being used on the right hand side, the result will be a float, even before it gets to the left hand side.

Number Trouble (NaN and Infinity)

NaN is shorthand for "Not a number", which means the result of a calculation is undefined. This is caused by dividing 0.0 by 0.0 or taking the square root of a negative number. Infinity is the result of a calculation that is too large to be normally represented by a floating-point number. It's commonly seen as the result of dividing a number by 0.0. Its opposite value, -Infinity, is the result of dividing a negative number by 0.0. These unexpected results are often hidden by variables. Check the value of your variables with print() to search for these and similar numerical problems.

color(0, 0, 0, 0) is black

The reason this doesn't work is that color(0, 0, 0, 0) creates an int that is simply '0'. Which means that fill(color(0, 0, 0, 0)) is the same as fill(0), which is...black. This is a problem of 'color' not being a real type, but just an int, plus the fact that we overload fill() to use both int/color for a color, and also an int for a gray. Since this is unlikely to be fixed anytime soon (if ever), there are multiple workarounds that you can use:

• use fill(0, 0, 0, 0)
• fill(c, 0) where c = color(0, 0, 0);
• color almostTransparent = color(0, 0, 0, 1);
• color almostBlack = color(1, 1, 1, 0);

Problems with Video

See the Video Issues page

Problems with the Serial Port

See the Serial Port Issues page

Problems with OpenGL

See the OpenGL Issues page

Common Issues (not bugs)

Things that are often perceived as bugs, but aren't actually 'broken'.

• If you write informal code (some test lines, no setup()) and want to add a function (eg. void foo() { println("Foo"); }) you will get an error: unexpected token: void. You need to wrap your lines of code (not the functions!) in setup(). Technically, that's because if your code has no setup() method, Processing will wrap it in a generated setup(). But Java doesn't allow nested methods, hence the error.

• If your code has methods (it's not just in static mode) or needs to run over time, it must have a draw() method, otherwise nothing will happen. For instance, without a draw(), this code will stop after the setup() method:

void setup() {
  size(400, 400);
}
 
void keyPressed() {
  println(key);
}

• An UnsupportedClassVersionError means that you're using code that was compiled for a later version of Java than is supported by Processing. As of the 2.0 releases, Processing supports Java 1.6. A message like

java.lang.UnsupportedClassVersionError: (Unsupported major.minor version 51.0)

means that the code was compiled for Java 1.7, which is not currently used with Processing.

• Any code that accesses the pixels[] array should be placed inside loadPixels() and updatePixels(). This can be confusing because it was not required in older code, i.e. with some alpha/beta releases in the 1.0 series. A complete description can be found in the reference for the pixels array.

• Unless you know what you're doing, you should not have a method in your sketch that's called run() (with no parameters, at least). This will break your sketch. Unfortunately, we can't explicitly disallow it, because some advanced programmers may need to write their own run().

• Why doesn't saveFrame (or saveStrings or saveBytes) write things to the data folder? All saveXxxx() functions use the path to the sketch folder, rather than its data folder. Once exported, the data folder will be found inside the jar file of the exported application or applet. In this case, it's not possible to save data into the jar file, because it will often be running from a server, or marked in-use if running from a local file system. With this in mind, saving to the data path doesn't make sense anyway. If you know you're running locally, and want to save to the data folder, use saveXxxx("data/blah.dat").

• Objects with alpha (lines or shapes with an alpha fill or stroke, images with alpha, all fonts) are displayed in P3D and OpenGL based on their drawing order. This creates some annoying effects like making things opaque if they're drawn out of order with objects above or beneath them. This is simply how most 3D rendering works, but is something that we'd like to hide from users in the future. As of revision 0114, the situation can be improved by adding hint(ENABLE_DEPTH_SORT) to setup(). However, the implementation is far from perfect. It may improve things or it may not, better support will arrive in a future release. (Bug 176)

• Names of sketches cannot start with a number, or have spaces inside. This is mostly because of a restriction on the naming of Java classes. I suppose if lots of people find this upsetting, we could add some extra code to unhinge the resulting class name from the sketch name, but it adds complexity, and complexity == bugs. :)

• Mind the capitalization of built-in functions. If a method or variable name is two words, usually the first word is lowercase and the first letter of the second word will be capitalized. For instance: keyPressed, movieEvent, mouseX, etc. If you have a function called mousepressed(), it won't be called when mouse events occur, because it needs the capital P on 'pressed'.

• On Mac OS X, the error message:

## Component Manager: attempting to find symbols in a component alias of type (regR/carP/x!bt)

is not something from Processing, it is a bug in Roxio Toast 5.2's Video CD Support extension. To suppress the messages, move "Toast Video CD Support.qtx" out of /Library/QuickTime (at least until you need to do Video CD work).

• On Windows, sometimes your programs will run in a window that has a Java coffee cup icon, instead of the usual Processing icon. This simply means that the application is being run outside of Processing as an external application. This happens when extra libraries, multiple source code files (more than one tab