GD
GDScript Error Handling
GDScript error propagation, assert patterns, and null safety conventions
Details
Language / Topic
GDScriptCategory
Error Handling
Rules
balanced
- Use `assert(condition, "message")` for programmer-error invariants during development — asserts are stripped in release builds, so never use them for runtime validation.
- Check `is_instance_valid(node)` before calling methods on node references that may have been freed — freed nodes become invalid pointers in GDScript.
- Use `push_error("message")` for non-fatal runtime errors you want logged without crashing — reserve `push_warning()` for degraded-but-recoverable conditions.
- Return a typed sentinel or `null` from functions that can fail, and document the contract: `func find_item(id: int) -> Item:` returns `null` if not found.
- Use `if not is_instance_valid(target): return` guards at the top of callbacks and signals that reference scene nodes.
- Use `@warning_ignore` annotation sparingly — only suppress warnings you have deliberately handled, and leave a comment explaining why.
- Validate `@export` node path variables in `_ready()` with `assert` to surface mis-configured scenes immediately at scene load time.