Reading the log file

The log file contains information on what portion of the game executed. Whenever something goes wrong, information on that also gets appending to the log. The information includes a specific error message, the location in the code to find the cause of the problem, and a stack trace which tells us how the game got to that location.

Log file locations

PC: Documents folder at Documents\ klei\donotstarve\log.txt
Mac: Documents folder at ~/Documents/Klei/DoNotStarve/log.txt
Linux: Klei folder at ~/.klei/DoNotStarve/log.txt


Understanding stack trace

As the game executes, it jumps from function to function, doing various things. Sometimes it jumps into a function which causes a problem, and it’s unable to continue executing. It remembers which functions it came from, and which lines of code it used to jump into functions.

The stack trace is essentially a collection of this kind of memory in a human-readable format (not counting people who can read binary).


Using the print function

Every time the code calls the “print” function (or equivalent), it also adds information to the log file. This is very useful as programmers/modders because we can write our own “notes” along the code to help us understand why it’s not working as we want it to.



Finding the error

The error which caused the crash usually prints to the log in a generic format. First you’ll have am error message prefixed with the location of the error, then directly below it you’ll see the stack trace information starting with “LUA ERROR stack traceback:”

For example,

Lets break that down and see what it means.

"...path/to/ds/data/scripts/util.lua:276:" This part tells us which line of code crashed the game. In this case, it was line 276 in util.lua.

"Could not find an asset matching path/to/asset.xml in any of the search paths." This is the error message, it tells us what went wrong. In this case, the game couldn’t find the file called “asset.xml” anywhere.

"LUA ERROR stack traceback:" This is just the generic starting line of the stack trace. It tells us the stack trace is printed below.

Remember, the format is something like this.

Due to the generic message being used for the stack trace, you can usually just search (ctrl+f) for “ERROR” in the log file and you’ll find this portion.

Sometimes, the crash won’t produce a well formatted stack trace error. In this case, you’ll need to do a little more investigation to figure out what’s wrong. Look through the log file and try to find things like “Could not load” or “Could not find”. You can even search (ctrl+f) for “could not” if you wish.


Putting it all together

You know what stack trace does, you know how to use the print function, and you’ve found your error. Now you might be wondering, “Well, that’s great, but how do I fix it?”

There isn’t any straight forward answer to this as there can be a variety of different problems, but there is a general set of actions you can take to help you figure out the answer yourself.

First, you want to actually read and understand the error message. It tries it’s best to tell you what’s wrong, but it doesn’t usually know why that’s a problem because it has no idea what you were trying to do. Basically, it thinks of it like “Hey man, why would you put this weird code here? It’s confusing me.”

Sometimes, it might realize that you made a small mistake, like missed a closing bracket, so it’ll point that out. Otherwise, it’ll just tell you what part of the code made it crash.

Remember, a healthy computer never makes mistakes, it just doesn’t understand you because it can’t think outside the box (literally, the computer box). You, on the other hand, can make mistakes, but you can also think outside the box. So you must try to understand what the computer is trying to tell you, and work with it to fix the problem.


Common errors

nil global variable

This might be the most common error you come across. It means that the code wasn’t able to access a variable because it is nil (not found).

There can be a number of reasons for this, here are some of the common ones.

  • You forgot to put some value into that variable
  • A function was supposed to initialize it, but didn’t work as you wanted it to
  • The variable is a parameter in a function, but nothing was passed in through it
  • Your variable is out of scope.

To fix it, figure out why the variable is nil. Use the stack trace to find where it was supposed to get its value from.

Usually, if the error is in modmain, you will need to access that variable from the GLOBAL table by using  GLOBAL.SomeVar instead of  SomeVar. Alternately, can also put  SomeVar = GLOBAL.SomeVar before the variable is needed (at the top of the script) and it won’t cause an error when you attempt to use  SomeVar.


nil parent variable

Similar to the one above. This one usually occurs when you attempt to access the child of a table that hasn’t been initialized correctly.
You can not use a child element ( such as parent.child  ) unless the parent has been previously declared ( parent = {}  ).

See this guide on parent-children for more detailed information.


nil value/variable in an expression

Like the first two, some variable (or evaluated value) is nil and the code tries to perform arithmetic (math) on it. Check the line which is causing the error, and see which values might be nil at that point in execution. Your stack trace will be really helpful here.


Missing asset error

Both of these occur when you tried to access a file that isn’t available in the correct folders. Check the folders to make sure you do have it there.

It might also be that you didn’t want to use the file at all, but forgot to remove that portion of the code. If so, simply go to the corresponding error line, and remove it.

You might also see this without the generic stack trace format, like so,


Missing syntax

This kind of error arises when you forgot to complete the syntax (brackets, commas, etc) of a portion of code.

Check on and around (usually before) the line specified in your error. You’re looking for any missing brackets (curly or normal), commas, “end”s, or any other small mistakes.

Note: A good code editor will spot these kind of errors automatically, so you’ll be able to catch them before you even test the code.


Missing “end” of functions or control statements

These are quite straightforward, but may be hard to spot. You might have some variations, such as “while” instead of “if”, but they’re all the same reason. The code is missing an “end” to close off a function or a control statement (if, else, while, etc).

A good way to spot it is to start looking from the beginning of the function or control statement specified, and reading down towards the error line. Look for any function or if statement that doesn’t end. Keep in mind that nested functions/statements need an “end” too, so you might have only one “end” instead of two if the nested one completes at the same place as the outer one.


Note: A good code editor will spot these kind of errors automatically, so you’ll be able to catch them before you even test the code.


The crash screen

Remember that crashed wall of text we talked of earlier? It actually contains a portion of the log.txt file. You might not even have to look through the log, in most cases. Try to compare them yourself to get a better understanding of how it works.