Godot Debugging Guide

Comprehensive debugging workflow and common issue resolution for Godot 4.x.

Output Methods

print() vs push_error() vs push_warning()

# print() — General output, filtered in editor output
print("Debug: position = ", position)
print("Debug: player health = ", player_health)

# printf-style formatting
printf("Player %s has %d health", player_name, health)

# push_error() — Shows in red, includes file and line number
push_error("Failed to load resource: ", resource_path)

# push_warning() — Shows in yellow, non-fatal issues
push_warning("Missing animation for state: ", state)

# load() returns null on failure — check before use
var data = load(risky_path)
if data == null:
    push_error("Could not load resource at: %s" % risky_path)

# Or with ResourceLoader for error codes
var err, data = ResourceLoader.load_interactive(risky_path)
if err != OK:
    push_error("Failed to load: %s (error code %d)" % [risky_path, err])

Editor Output Window

Access via Window > Debugger or Debug > Start Debugging. The output panel shows:

• Standard print output (gray)
• Warnings (yellow)
• Errors (red) with file/line info
• Custom logger messages

Debugger Panel

Built-in Debugger Features

1. Scene Tree — Visual tree of current scene with property inspection
2. Resources — List of loaded resources, check for leaks
3. Profiler — CPU and GPU usage breakdown
4. Remote Transform — Edit node properties in running scenes
5. Network Profiler — Monitor multiplayer traffic

Remote Debugging

# Connect to remote scene tree from editor
# When running in debug mode (F6), the editor connects automatically

# Access remote nodes
func get_remote_node(path: String):
    var node = get_node(path)  # Works on local and remote
    return node

Profiling Workflow

CPU Profiler

Profile > Start Profiling in the editor
Then view: Profile > CPU Usage or Profile > Frame Time Graph

Key metrics:

• Frame time — Should be under 16.67ms for 60fps
• Physics FPS — Should match target (usually 60)
• Script time — Time spent in GDScript/C# code
• Draw calls — Number of GPU draw calls per frame

Memory Profiler

Profile > Memory Usage
Check for:
- Growing resource count over time
- Unfreed scene instances
- Large textures not being unloaded

GPU Profiler

Project Settings > Rendering > Debug > GPU Profiling = On
Then: Profile > GPU Usage

Common Error Patterns & Fixes

"Script class 'XXX' does not exist in current project"

• Cause: Autoload script reference broken after rename/move
• Fix: Re-add the autoload in Project Settings > Autoload

"Cannot instantiate non-imported scene: res://..."

• Cause: Scene file not saved or path is incorrect
• Fix: Open the scene in editor and save it, verify path

"Invalid get index 'XXX' (on base: 'Node2D')"

• Cause: Accessing a property that doesn't exist on the node
• Fix: Check node type and available properties, use has_method() or is() checks

"Failed to connect signal"

• Cause: Method name mismatch or signal doesn't exist
• Fix: Verify signal exists on source node, check method signature matches

Export/Build Errors

Network Debugging

Multiplayer API Inspection

# Check connection status
print("Connected: ", Network.multiplayer.is_connected_to_server())
print("Peer count: ", Network.multiplayer.get_peers().size())

# Log RPC calls for debugging
func _rpc_debug_message(msg):
    print("[RPC] ", msg)

# Monitor network traffic
# Use Profile > Network Profiler in the editor

Lag Compensation Debugging

# Log timing information
print("Server time: ", get_tree().get_network_unique_id())
print("Local latency: ", Network.multiplayer.get_connection_status())

Godot 4.7 Debugging Notes

• Perfetto tracing — New built-in Android profiler for detailed performance analysis
• New editor log improvements — Better error messages with more context
• tween_await() debugging — Use await breakpoints in C# debugger for animation sequences

Debug Utility Functions

class_name DebugUtils extends Node

static func draw_rect_debug(rect: Rect2, color: Color, lifetime: float = 0.0):
    # Draw debug rectangle (use with CanvasItem.draw_rect)
    pass

static func log_tree(node: Node, indent: int = 0):
    # Print scene tree for debugging
    var prefix = "  ".repeat(indent)
    print(prefix + node.name, " (", node.get_class(), ")")
    for child in node.get_children():
        log_tree(child, indent + 1)

static func check_node_ready(node: Node):
    # Verify node is ready before accessing children
    if not node.is_inside_tree():
        push_error("Node not in tree: ", node.name)
    return node.is_inside_tree()

MCP Bridge Tools (Optional — Live Editor Integration)

When the MCP bridge is running (Phase 2), these tools provide live debugging capabilities:

• debugger_output — Read real-time debugger output from the running scene
• output_log — Read Godot's output log with level filtering (error/warning/info)
• scene_run / scene_stop — Start and stop scenes for testing fixes
• pause_resume — Pause execution to inspect state at breakpoints
• script_validate — Validate scripts without leaving the agent workflow
• scene_tree — Inspect runtime scene hierarchy for missing nodes

Note: MCP tools require the Godot editor to be running with the MCP plugin enabled. Skills work independently without the bridge.

References

• Debugging Guide
• Profiler Deep Dive
• Network Debugging