Anatomy of an Error Message

Anatomy of an Error Message N/A

You will get error messages when making your game. This is inevitable. This is meant to be a basic guide to reading these errors, so you can understand where they're pointing to.

Game Info
The top section of the error message is dedicated to listing information about your game. It's usually structured like this:
  • The version of Essentials you're using, written as [Pokémon Essentials Version X]
  • The version of the hotfixes you have installed, written as [vX Hotfixes Y]
  • Any major plugins you've added, like EBDX, the Gen 8 project, or the ZUD plugin
This section isn't so much for you, the developer, as it is for other people reading your error message, to give them the context of what you're working with.

Important - A resource being mentioned in your error message does NOT mean that the resource is the cause of the problem. (Please, Goli and Lucidious are very tired of explaining that their resources are not, in fact, the cause of every problem ever)

(Not sure about the actual name for this section, honestly. To avoid any confusion, I'll be calling this section as a whole "the message section", and the specific line just "the message" )

This usually consists of the exception and the message. The exception is the kind of error you're getting, and the message tells you some details about the problem.

Some errors even have custom messages telling you exactly how to fix them, like this one -
Line # shouldn't begin with '('. Try putting the ( at the end of the previous line instead, or using 'extendtext.exe'.

If your error is connected to a specific event, you'll usually also be given the specific event (gives ID number, coordinates, and map), and the script command written in full. (This will sometimes be annotated with the specific trouble spots)

I've tried to list off the exceptions I've seen, accompanying messages (variable points in italics) and the usual causes for them. This list isn't meant to be comprehensive or give every solution to every error, it's just supposed to be a sort of general knowledge base.
  • ArgumentError - The most common causes of this is giving the wrong arguments to a method. (I have seen it appear for a few other errors, but I couldn't really tell you why they're categorized as ArgumentErrors and not something else.)
    • When using a method, you either gave the wrong number of arguments. could be too few or too many),
      • Message: wrong number of arguments (# for #)
      • Message: wrong number of arguments (given #, expected min..max)
    • When using a method, you gave the right number of arguments, but they weren't the right class. (for example, giving a trainer when the game expected a Pokemon)
      • Message: Invalid argument passed to method. Expected (object) to be one of [class,class], but got class.
    • You tried to compare a numerical value with something that wasn't a number. (A string of text, a nil object, etc.)
      • Message: Comparison of X with Y failed
    • You tried to rename your game to include the accent in Pokémon, but you did so through RPG Maker's Title Change option rather than through Game.ini. (Thanks to Golisopod User for this one!)
      • Message: invalid byte sequence in UTF-8
    • You have a module or something similar added to your save file as part of a plugin, but then you removed the plugin.
      • Message: undefined class/module name
  • Errno::ENOENT - The game is looking for a file, but it can't find it at the given filepath. The most common one of these is missing .dat files, which means you need to recompile your game.
    • Message: File filepath not found
  • Hangup - If a script takes too long to load (usually over ten seconds), the game will force itself to close, and return the error message. These should usually autosave the game before crashing. Sometimes, these aren't specific to a game's code - you can get hangup errors if RMXP becomes unresponsive, for example - and so you might occasionally encounter players getting hangup errors when you don't. (Thanks to Maruno and Vendily for explaining this more!)
    • Message: The script is taking too long. The game will restart.
  • NameError - You're referring to something that hasn't been defined. Depending on the context/capitalization, the game will say it's a constant, variable, method, etc., which may or may not be true. Very similar to NoMethodErrrors.
    • Message: uninitialized constant Interpreter::name
    • Message: uninitialized constant class::name
    • Message: undefined method name for class class
    • Message: undefined local variable or method name for class class
  • NoMethodError - You're trying to use a method on an object, but the method doesn't exist for that object. Can also happen if you're using a non-existent method in an event.

    Be careful - this can also come up when you try an object on a NilClass object - an object that doesn't exist. For example, say I just ran the code pkmn.nicknamed? without defining pkmn first. I would get an error saying NoMethodError - undefined method nicknamed? for nil:NilClass. nicknamed? is still defined, it’s just that it was being applied to something that didn’t exist.
    • Message: undefined method `methodname' for class
    • Message: undefined method `methodname' for event
  • RuntimeError - These most frequently appear when there's an error in an event's script command. When this is the case, they'll often be accompanied by another error detailing the problem with the script. They also tend to show up when there's a problem compiling/retrieving PBS data.
    • Your event is running a script with an error in it.
      • Message: Script error in event ID# (coords X,Y), map ID# (Map Name)
      • This will usually be accompanied by the full script command
    • You're referring to an ID that wasn't defined. (or the ID was defined, but you're not referring to it correctly)
      • Message: Unknown ID IDNAME
    • You've somehow messed up with the PBs - put the wrong values into the wrong fields (a lot less common now that the PBS has been rearranged), defined something twice, etc.
      • Message: Field entry is not a class
        File PBS/file.txt, section #, key section
      • Message: pbs ID 'IDNAME' is used twice.
      • Message: Bad line syntax (expected syntax like XXX=YYY) (from older version of Essentials)
    • You're missing a graphic for something defined in the PBS. (Pokemon/Item/Trainer/etc).
      • Message: Filename is nil (missing graphic).
  • SyntaxError - The simplest error to deal with. These are just typos in scripts. Missing brackets/parenthesis, missing ends, things not on the right lines, etc. By far the most common is running a method across multiple lines, and starting the second line with a (. It's so common, in fact, that there's a custom error message explaining exactly what to do to fix it...
    • "unterminated string meets end of file" means that you're started a string with " but never closed it out. It's usually not too hard to find, as strings are highlighted in purple in the script editor (or grey in Notepad++), so all the text should be highlighted after the ".
  • SystemStackError - Typically caused by recursive errors. Recursive errors are when code loops back in on itself, with no way to get out. For example, say you created a method def pbDoSomething, and this method is supposed to run pbDoSomething. Well, when you call pbDoSomething, it'll run pbDoSomething, which tells it to run pbDoSomething, which tells it to run pbDoSomething... I'm sure you get the picture. Sometimes, these errors don't have the backtrace attached, which can make things tricky.
    • Message: Stack level too deep
  • TypeError - The game is trying to convert an object into another object or class, but is unable to do so. This is most commonly because the object was never actually defined, and you can't convert a NilClass object into anything else, but it can happen with existing objects as well. You may also get this error when trying to store an object in save data that can't be serialized. (For example, saving an image as part of the save file)
    • Message: no implicit conversion of class into class
    • Message: no marshal_dump is defined for class class
    • Message: class can't be coerced into class
    • Message: can't clone class

It's worth remembering that similar problems can result in different exceptions. For example, comparing a string to a fixnum will get you an ArgumentError, but trying to convert a string to a fixnum will get you a TypeError. A missing graphic could return an Errno::ENOENT, but the game might be trying to get a bitmap from the file, in which case it's not until it tries to interact with the (now nil) object that you'll get your error - a NoMethodError.

The exception can be useful for identifying problems, but you'll probably find the most important information by reading the message and checking the backtrace.

The backtrace of an error message is a roadmap of the scripts the game went through before arriving at the error message. It starts with the line that resulted in the error, then goes back to what caused that bit of code to be used, then back to what bit of code caused that, and so on.

Backtraces tend to be pretty long - usually taking up half the error message screen - but you usually don't need to concern yourself with most of it. An error is usually going to be identified within the first few lines of the backtrace - an error that gets passed down through several methods is probably a sign of a bigger problem in how you set something up.

Each entry in the backtrace is set up like this:

(script number):(script name):(line number):in 'method name'

  • Script number is the number of the script in the script editor. Scripts are numbered top to bottom, starting at 000. If the script in question is from a plugin, it will instead be [Plugin Name].
  • Script name is the name of the script section. Scripts from a plugin will include ".rb" at the end of their name.
  • Line number is either the number of the line where the error occurred, if it's the first entry in the backtrace, or the line that called the previous method in the backtrace.
  • Method name is either the method that was being used when the error occurred, if it's the first entry in the backtrace, or the method that led to the previous entry in the backtrace.

An Example
This is an error that was tripping people up a lot in v19. (recreated in v20 here) It's the "name your rival" event from the default maps.

Let's start by honing in on the Message section -
Script error in event 15 (coords 22,13), map 31 (Route 3)
Exception: NoMethodError
Message: undefined method `width' for nil:NilClass

***Full script:
name = pbEnterNPCName(
_I("Rival's name?"),
pbSet(12, name)
I can see that I'm getting an "undefined for NilClass" error here, so I know that something's missing. I can also see that whatever I need, I'm supposed to be able to get the width of it. (That might clue you in already - there's only a few things you'd get the width of in a game...)

But "width" isn't referred to anywhere in my script command. So I'll need to look at the script editor to see the whole method, and get an idea of what it wants.

My backtrace is pointing me to UI_TextEntry -
300:UI_TextEntry:451:in `pbStartScene'
300:UI_TextEntry:765:in `pbStartScreen'
300:UI_TextEntry:789:in `block in pbEnterText'
Let's look at line 451, and some of the lines above it.
    when 3   # NPC
      @sprites["shadow"] =, 0, @viewport)
      @sprites["shadow"].x = 66
      @sprites["shadow"].y = 64
      @sprites["subject"] =, @viewport)
      charwidth = @sprites["subject"].bitmap.width
So, the game can't get the width of @sprites["subject"].bitmap. We can see that @sprites["subject"] just got defined right above it, and it's a TrainerWalkingCharSprite.

I could go back through the script and explain exactly how you could figure it out, but I think it's pretty clear here - I'm trying to call a graphic that's not there. So when the game tries to check the width of the bitmap, it can't, because it had no image to make a bitmap with.

I can also infer from the class name that the TrainerWalkingCharSprite is probably the sprite of my rival walking in place when I name him.

Let's look back at my original script command.
name = pbEnterNPCName(
  _I("Rival's name?"),
  1, Settings::MAX_PLAYER_NAME_SIZE,
pbSet(12, name)
Now, again, I could look through the scripts to see the specific arguments that pbEnterNPCName uses. (And it's always a good idea to do so when encountering a new method! Just search for "def method" with Ctrl+Shift+F!) But I can work out that "trchar004" is the image name just by process of elimination. (I'm obviously not naming any files "1" or "Settings::MAX_PLAYER_NAME_SIZE", and I can see where the game uses the text "Blue" and "Rival's name?")

And since I know this is his walking sprite, I'll probably want to check Graphics/Characters first. Sure enough, there's no file named "trchar004" there (or anywhere else, for that matter), but there is an overworld sprite for Blue, named "trainer_RIVAL1". I could rename this file to "trchar004", or keep the current naming convention and just change my event.

None required.
First release
Last update
5.00 star(s) 4 ratings

More resources from TechSkylander1518

Latest reviews

This helped me debug some PBS errors when porting my maps over to Essentials v21 and I am sure this will help me solve many future bugs.
I now understand errors more than I used to! Thanks!
I'm glad this was able to help!!
I definitely can use a guide like this for troubleshooting.
I'm replying extremely late but thank you!! I hope this has been helpful!