Debugging

Logs

The engine prints to stdout/stderr. Two macro families produce log output:

• print_line, print_verbose, print_warning, print_error (core/error/error_macros.h) — go through the engine's Logger chain. The root logger is set up in Main::setup. By default it tees to stdout and to a file (user://logs/godot.log rotated).
• ERR_FAIL_*, WARN_PRINT, ERR_PRINT macros — convenience wrappers that include file/line context.

Pass --verbose to enable print_verbose output. Pass --quiet to suppress informational chatter.

The GODOT_VERBOSE environment variable has the same effect as --verbose.

Running under a debugger

Linux/macOS:

gdb --args ./bin/godot.linuxbsd.editor.x86_64 --path my-project
lldb -- ./bin/godot.macos.editor.universal --path my-project

Windows: open the binary in Visual Studio (the godot.natvis debug visualizer makes Variant/HashMap/etc. legible).

The engine ships with dev_build=yes debug symbols; for release-grade reproductions use target=template_debug.

Crash handlers

Every platform has a crash_handler_*.cpp that installs a top-level exception / signal handler and prints a symbolicated stack trace before the process dies:

• Linux/BSD — libbacktrace.
• Windows — DbgHelp + minidump.
• macOS — Mach exceptions + backtrace_symbols.
• Android — Bionic backtrace.

When a crash report comes in from a user, ask for the engine's tail-of-log output; the stack trace is at the bottom.

Editor remote debugger

When the editor launches a project (Play button), it opens a TCP listener and the running game connects back through EngineDebugger (core/debugger/). Available panels in the editor's bottom panel:

Panel	Shows
Stack Frames	Live call stack at a breakpoint
Variables	Scope variables at the current frame
Errors	Engine / script errors as they happen
Profiler	CPU profiling per frame, function timings
Visual profiler	Per-pass GPU timing on supported drivers
Network profiler	Bandwidth + RPC traffic for multiplayer
Monitor	Engine counters (FPS, memory, draw calls, RIDs, …)
Video memory	Live texture/mesh/material resource list
Misc	Object DB profiler counts, audio output

The "Remote scene tree" tab shows the running game's scene tree live; you can inspect properties, call methods, and apply changes that survive the running session (and optionally write back to disk).

Live edit

The editor supports limited live editing of the running game:

• Move/scale/rotate transformation changes apply immediately.
• Property edits propagate.
• Some script changes propagate; structural changes (signature changes) require a restart.

This is implemented via the same EngineDebugger channel — the editor sends "live ops" to the running game.

Profiling without the editor

For deeper profiles, build with the engine's profiling backends:

• --cpu-profiler (when supported on the platform) feeds Tracy or dumps callgrind-style files.
• Engine::set_max_fps(0) + a profiler attached to the binary captures hot paths.
• RenderingServer's request_frame_drawn_callback lets you measure GPU frame time precisely.

For GPU profiling, use vendor tools — RenderDoc, Nsight Graphics, Radeon GPU Profiler, Xcode Metal frame capture. The Vulkan and D3D12 drivers tag command buffers (vkCmdBeginDebugUtilsLabelEXT, ID3D12GraphicsCommandList::BeginEvent) so capture tools group commands sensibly.

Tracking down memory leaks

OBJECT_TRACKING_ENABLED is on for dev_build=yes builds; Object::print_orphan_nodes() and Engine::print_object_db() (also exposed on the editor's "ObjectDB profiler" via modules/objectdb_profiler) list lingering objects. Reference cycles are easy in scripts — WeakRef is the antidote.

For native leaks, ASAN works:

scons use_asan=yes
./bin/godot.linuxbsd.editor.x86_64 --headless --quit

The engine clean-up path runs through Main::cleanup which tears down singletons, scene tree, servers, and finally the OS. Run with LSAN_OPTIONS=verbosity=1 to see leak summaries.

Reproducing user bugs

Most useful artifacts to ask for:

1. Engine version (Help → About in editor, or the splash log).
2. OS + GPU + driver version (the engine prints them to the log on startup).
3. A Minimal Reproduction Project that triggers the issue.
4. The --verbose output of running the project.
5. The stack trace from the crash handler if it was a crash.

The official bug template under .github/ISSUE_TEMPLATE/ collects these.