GDScript print and Debugging: print_rich, push_error, assert

print() is the first debugging tool: show a value, run the game, read the Output panel. Make the line say what it is:

extends Node

func _ready():
	var velocity := Vector2(120, -340)
	var on_floor := false
	var state := {"hp": 3, "coins": 12}

	print(velocity)                                    # just a value
	print("velocity: ", velocity, " on_floor: ", on_floor)
	prints("state", state)                             # spaces between values
	print("speed %.1f" % velocity.length())

(120.0, -340.0)
velocity: (120.0, -340.0) on_floor: false
state { "hp": 3, "coins": 12 }
speed 360.6

• print(a, b) joins values with nothing between them, prints() with spaces and printt() with tabs.
• Arrays, dictionaries, vectors and nodes all print in a readable form.
• A print in _process() runs 60 times a second and floods the Output panel. Print only when something changes, or every 30th frame.

Warnings and Errors from Your Code

push_warning() and push_error() report a problem with the line it came from. The editor lists them in the Debugger's Errors tab, so they do not get lost among prints:

extends Node

func load_level(number: int) -> void:
	if number < 1:
		push_error("Level number must be at least 1, got %d" % number)
		return
	if number > 10:
		push_warning("Level %d is not finished yet" % number)
	print("Loading level ", number)

func _ready():
	# Reports a warning and an error on purpose.
	load_level(12)
	load_level(0)

WARNING: Level 12 is not finished yet
     at: push_warning (core/variant/variant_utility.cpp:1033)
     GDScript backtrace (most recent call first):
         [0] load_level (res://main.gd:8)
         [1] _ready (res://main.gd:13)
ERROR: Level number must be at least 1, got 0
   at: push_error (core/variant/variant_utility.cpp:1023)
   GDScript backtrace (most recent call first):
       [0] load_level (res://main.gd:5)
       [1] _ready (res://main.gd:14)
Loading level 12

The backtrace lists the calls that led there, newest first, so you see both where the problem was found and who asked for it. Neither function stops the game. The Run button on this page lists errors and warnings before the printed lines; Godot's Output panel shows everything in the order it happened.

assert: Check What Must Be True

assert(condition, message) stops with an error when the condition is false:

extends Node

func set_volume(value: float) -> void:
	assert(value >= 0.0 and value <= 1.0, "volume out of range: %s" % value)
	print("volume ", value)

func _ready():
	# The second call fails on purpose, with an error.
	set_volume(0.5)
	set_volume(3.0)

SCRIPT ERROR: Assertion failed: volume out of range: 3.0
          at: set_volume (res://main.gd:4)
          GDScript backtrace (most recent call first):
              [0] set_volume (res://main.gd:4)
              [1] _ready (res://main.gd:10)
volume 0.5

Asserts only run in debug builds. An exported game skips them entirely, so never write assert(spawn_enemy()): in the release build the enemy would never spawn.

Where Was This Called From?

print_debug("jump pressed")   # the text plus the file, line and function
print_stack()                 # the whole call stack at this point
var stack := get_stack()      # the same as an array of dictionaries

print_stack() answers "who called this function with the wrong value?" without adding prints to every caller.

print_rich: Colors in the Output

print_rich() reads BBCode tags, so an important line stands out in the editor's Output panel:

print_rich("[color=green]Level loaded[/color] in [b]%d ms[/b]" % 42)
print_rich("[color=red]Player died[/color]")

In a terminal it prints color escape codes instead, so keep plain print() for logs that end up in files.

Breakpoints and the Debugger

Prints show values you thought to print. The debugger shows all of them:

1. Click in the gutter left of a line number (or press F9). A red dot appears.
2. Run the game. When it reaches the line, it pauses.
3. The Debugger panel shows the call stack and every local and member variable. Step over (F10) runs one line, step into (F11) enters a call.

The breakpoint keyword on a line of code does the same as the red dot. When a script error happens while running from the editor, the debugger also pauses on the failing line.

The Remote Scene Tree

While the game runs, the Scene dock shows a Remote tab: the live tree of the running game. Click a node to see its current property values in the Inspector, and change them to test a fix without restarting. It is the fastest way to answer "is my enemy even in the scene?" and "why is this label invisible?"

The error messages page explains the errors you will meet most often.