debug-featAn occasional post in the forums may be something like, “My app works fine in the Simulator, but doesn’t work on the device. What’s wrong? Must be a Corona bug…” or “My program just gives me a black screen. What’s wrong? Must be a Corona bug…

Often, these posts are made because the developer doesn’t use — or doesn’t have access to — the correct tools that can help determine what the problem is.

Here at Corona Labs, and for those wonderful community members who volunteer their time to help solve your problems, these type of posts provide almost no useful information. For example, from one of the examples above, we don’t know:

  • Are you on Mac OS X or Windows?
  • Are you building for iOS or Android?
  • What version of Corona SDK are you using?

In almost every case, we need that information to form an initial guess of what the issue is. However, even more important is seeing an error message that can truly help diagnose the problem. Sometimes, your response may be, “There are no errors, only a black screen.” In fact, there are errors, or the program would be working — most likely you just don’t know where to see these error reports.

Essentially, Corona produces two types of error messages:

  1. Those that pop up on the screen (assuming “Show Runtime Errors” is enabled in the Simulator preferences).
  2. Errors that only appear in the console log.

Typically, the error you see on the screen is only part of the picture. There’s usually more information in the console log, so read further to learn how to see that console log and make use of it.

Viewing Error Messages

There are various ways to see error reports while developing with Corona. One is to use the Terminal (Mac) or console window (Windows) to view diagnostic output and the value of print() statements from within your code. While this practice is considered “old fashioned” to some, it can be quite effective.

On Windows, the console loads automatically alongside the Simulator, but on Mac OS X, you need to “link” the Terminal to the Simulator. If you’re running the Corona Simulator by itself, please close and quit the Simulator for a moment — we need to reload it so the Terminal works in unison. Now, instead of opening Corona Simulator from the application folder, open Corona Terminal. The Terminal will load, then it will automatically open the “Corona Simulator Welcome Window” where you can choose the Simulator option. On Windows, the equivalent of the Terminal is the console window, which will load automatically when you start the Simulator.

Another option is to use an Integrated Development Environment or IDE. These applications capture the output from Corona SDK and show it within the program.

No matter which option you prefer, the messages reported are critical to debugging your app. However, for new users, these messages may be confusing or, in more advanced situations, virtually impossible to understand.

Basic Sample

Let’s start with a simple example:

And when we run this code, we receive an error message as follows:

What does this mean? Well, first and foremost, notice the 86 around the middle of the second line. This means that the error occurred on line 86 of the file name that precedes it, in this case game.lua.

What follows the colon is the actual error message:

This tells us a little bit about the problem. Immediately, we know that there is some problem with background. More specifically, it is nil. But why is this so? The error message tells us some information but not all of it. Looking at the log file, however, reveals a bit more:

That’s a lot of information, but it provides two critical pieces to help isolate the issue. First, inspect the line right above the Runtime error line:

Well, in fact, the file is named background.jpg. The extra d in the file name causes the file to not be found by the display.newImageRect() call, triggering a program crash.

In addition to spelling the file name correctly, watch for case-sensitivity! This is actually a very common error when testing an app on a device for the first time. File names on the device are case sensitive, but they aren’t in the Simulator. Look for this warning and always adhere to the rules of case-sensitivity.

Stack Traceback

The second important part of the log file is called the “backtrace” or “stack traceback”. This reveals a “history” of where the problem occurred. In this case, it happened in game.lua at line 86. However, this line is actually contained within the scene’s createScene function which begins at line 13. In turn, that createScene was called via a dispatchEvent() call from a gotoScene call. Since these two exist in Storyboard’s core, there won’t be line numbers or module names, but you can see that the call happened at line 72 of menu.lua.

In essence, this is a trace of where the call originated. For this particular error, the backtrace isn’t very important since the basic “WARNING:” message revealed the problem. However, there will be times where your error happens back in the call history.  In this case, there may have been an error in menu.lua at line 72 that didn’t cause its problems until later. Using the stack traceback lets you work back through the code to find where the issue originated.

Viewing Error Messages

Both iOS and Android devices produce console logs as well as the XCode Simulator. Please inspect the following options:

XCode Simulator

spotlightFor the XCode simulator, the easiest way to access the Console is to click on the magnifying glass in the top right bar on your Mac. This brings up Spotlight Search. From there, type console. The first hit is the Console application. Simply click on it to launch it. Using this, you can see both the print() statements from your app and also any errors Corona SDK generates.

iOS Devices

The easiest way to debug on Apple devices is to use the Xcode Organizer. From the “Window” menu in Xcode, choose “Organizer.” It will bring up a screen that looks like this:


Now, you must “tether” your device (connect it to the computer via its charging cable) and wait until it appears in the left column. When it does, select it. You may also need to click the button in the middle that says “Use device for development.” Once you’ve done this, click on the “Console” link (circled in red in the screenshot) and view your console messages there.

Android Devices

Android can be debugged in a similar fashion. It’s a bit more “command-line oriented,” but once you figure out the commands, it’s a bit quicker to install apps, look at the log as your apps run, and view the error messages.

First, you have to install some free tools from Google called the Android Debug Bridge tools. For details on this, please see our Android Signing and Building guide and scroll to the “Debugging” section at the bottom.

Once these tools are installed, you can use the ADB command line tools. For debugging purposes, use the command line command:

With your Android device tethered, simply type that command in from your Terminal screen (or cmd window in Windows) and watch the messages appear on your monitor.

Like iOS, you may have to put your device into “developer mode” to gain this ability. Different devices and versions of Android do this in different manners, so we suggest that you search online for your OS and “developer mode” to locate the instructions.

In Summary…

Being able to read and understand these various log files and error reports can empower you to discover why your app is misbehaving. Even if you can’t solve the issue by yourself, this information is extremely valuable to others when you ask for help in the forums. At the very least, you should provide the error message and the full stack traceback, not just one small part of it. Doing so will assist the generous volunteer developers in the forums and, hopefully, bring about a quick resolution to your issue.


Tutorial: Basic Debugging