Skip to main content

Debugging

Every mod developer spends more time debugging than writing fresh code. The secret is that bugs are not random bad luck: they leave footprints. If you know where to look and how to interpret what you find, you can fix in two minutes what would otherwise cost you an evening of frustration.

The log file is your flight recorder​

When an unhandled exception occurs in SHVDN, the game does not pop up an error dialog. It simply shuts down the offending script while the rest of the game keeps running as if nothing happened. The crash details are written to ScriptHookVDotNet.log, located in your main GTA V folder.

Open this file whenever a script fails to react. Scroll to the very bottom. You will see lines that look like this:

[14:32:01] [ERROR] Script 'MyFirstMod' terminated with an unhandled exception:
System.NullReferenceException: Object reference not set to an instance of an object.
   at MyFirstMod.OnTick(Object sender, EventArgs e) in C:\Projects\MyFirstMod\MyFirstMod.cs:line 28

Reading the stack trace​

This trace tells you three vital facts:

  1. The error type: System.NullReferenceException. You tried to read a property or call a method on a variable that was null.
  2. The method: MyFirstMod.OnTick. The crash happened inside your tick handler.
  3. The exact line: line 28. Open your file in Visual Studio, press Ctrl+G, type 28, and look at the line.

In nine cases out of ten, a NullReferenceException on line 28 means you wrote Game.Player.Character.Position before the player character had finished spawning into the world.

The three most common beginner traps​

  • Accessing entities before they exist: During game load or right after a player switch, Game.Player.Character can be null for several frames. Always check: 
    if (Game.Player.Character == null || !Game.Player.Character.Exists())
    {
        return;
    }
  • Unnoticed build errors: You hit build, but compiler errors occurred in the background. You assumed the DLL updated, but the folder still holds the old binary. Always check the build output for Build: 1 succeeded.
  • Targeting the wrong .NET Framework: ScriptHookVDotNet 3 requires .NET Framework 4.8. If your project targets .NET 6, .NET 8, or .NET Standard, SHVDN will refuse to load it.

Using your AI tutor for debugging​

When you hit an error you do not understand, do not paste your entire project into an AI and ask "make it work". That teaches you nothing and often introduces three new bugs.

Instead, ask focused questions:

  • Paste the exact stack trace and the five lines of code surrounding that line.
  • Ask: "What can be null on this line, and how do I guard against it defensively?"
  • Verify the AI's explanation against your knowledge of the pipeline before accepting the suggestion.

Now that you have the fundamentals of scripts, data, control flow, input, and debugging, you are ready for your first real milestone project: Project 01 Hello GTA.