Posted on by

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:

85: local background = display.newImageRect( "images/backgroundd.jpg", 570, 360 )
86: background.x = display.contentCenterX
87: background.y = display.contentCenterY

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

Runtime error
...s/rmiracle/Projects/Jailbreak/game.lua:86: attempt to index local 'background' (a nil value)

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:

attempt to index local 'background' (a nil value)

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:

WARNING: Failed to find image(images/backgroundd.jpg)
Runtime error
...s/rmiracle/Projects/Card Game Guy/Jailbreak/game.lua:86: attempt to index local 'background' (a nil value)
stack traceback:
 [C]: ?
 ...s/rmiracle/Projects/Jailbreak/game.lua:86: in function <...s/rmiracle/Projects/Card Game Guy/Jailbreak/game.lua:13>
 ?: in function 'dispatchEvent'
 ?: in function 'gotoScene'
 ...s/rmiracle/Projects/Jailbreak/menu.lua:72: in function <...s/rmiracle/Projects/Card Game Guy/Jailbreak/menu.lua:70>
 ?: in function < ?:218>

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:

WARNING: Failed to find image(images/backgroundd.jpg)

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:

xcode02

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:

adb logcat Corona:v *:s

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. Sometimes errors are generated by other things besides Corona SDK that you need to see. If you do not see errors with the above command, you can see the entire log with this command:

adb logcat

This will stop the filtering for just Corona output.

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.


Posted by . Thanks for reading...

10 Responses to “Tutorial: Basic Debugging”

  1. sangam

    i am also facing same issue, when i install the running game from corona build -android to android device,
    then it gives blank screen. but same game is running in simulator very well.
    on corona consol no any error, warning its showing.

    i am using-
    Windows-os
    Android-device and
    version of Corona SDK are 2013.2076.

    so, please if you have any idea then share with me…thanks in advance

    Reply
    • Rob Miracle

      Hi @sangam. The blog post above starting at “Android Devices” tells you how to look at the log file generated by the device where any error messages would be. The Corona console doesn’t show the device errors.

      As a side note, you should update to build 2100, though it’s probably not going to fix the error you are having.

      Rob

      Reply
      • sangam

        Hi,Mr.Rob.
        i updated my Corona SDK with new version 2013.2100. but still i m not able to get any error on simulator output control when run my app and on device it shows still black screen. as you told “probably not going to fix the error” so plz guide me with accurate process to handle that error.

        Reply
  2. Neel

    Hey Rob i just installed the .ipa file in i-pad(ios-7). Application installed successfully but when i open that app screen remains black. no console msgs and no exception reported in console log. i am confused i am using the version V2013.2100 which is graphics2.0 compatible. can you please tell me so i can fix the problem and i am a starter so i can not access the daily builds also please help!.
    Thanks

    Reply
    • Rob Miracle

      There is little I can do with out more information as to what’s going on. I would suggest opening Xcode and then using it’s Organizer (SHIFT-CMD-2) and use it to install the app directly (no need to make a .ipa file, it will install the App Bundle directly. Then you can follow the instructions above on doing this. There should be some information in the “Console” log that indicates what’s going on.

      This sounds like a case where you might have a file name that’s running into case sensitivities problem.

      Rob

      Reply

Leave a Reply

  • (Will Not Be Published)