GDScript null and is_instance_valid(): Freed Objects

null means "no value". A variable with no value and no type starts as null, and so does any variable that holds an object until you give it one:

extends Node

var target: Node = null

func _ready():
	print(target)
	print(target == null)
	if not target:
		print("No target yet")
	target = self
	if target:
		print("Target: ", target.get_class())

<null>
true
No target yet
Target: Node

null counts as false in an if, so if target: reads "if there is a target".

Using a null Value Is an Error

Calling a method or reading a property on null stops the function:

extends Node

func _ready():
	# This stops with an error on purpose.
	var player = null
	print("before")
	player.jump()
	print("never printed")

SCRIPT ERROR: Invalid call. Nonexistent function 'jump' in base 'Nil'.
          at: _ready (res://main.gd:7)
          GDScript backtrace (most recent call first):
              [0] _ready (res://main.gd:7)
before

base 'Nil' is Godot telling you the value was null. The usual causes: a $NodePath that does not match the scene, an @onready variable read before _ready(), or a function that returned nothing.

Default Values Instead of null

Dictionaries return null for a missing key with get(), or a default you choose:

extends Node

func _ready():
	var save := {"name": "Ana"}
	print(save.get("level"))
	print(save.get("level", 1))
	var title = save.get("title")
	print(title if title != null else "Untitled")

<null>
1
Untitled

Freed Objects and is_instance_valid()

When a node is deleted, variables that point at it do not turn into null. They point at a freed object, and using one is an error. is_instance_valid() tells the two apart:

extends Node

func _ready():
	var enemy := Node.new()
	add_child(enemy)
	var remembered := enemy

	enemy.queue_free()
	print(is_instance_valid(remembered))      # still here this frame
	print(remembered.is_queued_for_deletion())

	await get_tree().process_frame            # the frame ends, the node is deleted
	print(is_instance_valid(remembered))
	print(remembered)

true
true
false
<Freed Object>

queue_free() deletes the node at the end of the frame, which is why the first check is still true. After that, remembered holds a <Freed Object>. Writing to it fails with an error like:

Invalid assignment of property or key 'name' with value of type 'String' on a base object of type 'previously freed'.

When to Use Each Check

A homing missile is the classic case for is_instance_valid():

var target: Node2D

func _physics_process(delta):
	if not is_instance_valid(target):
		queue_free()  # the target died, so the missile goes too
		return
	position = position.move_toward(target.position, 300 * delta)

An even safer habit is to clear the reference when the node leaves, by connecting to its tree_exiting signal and setting the variable back to null.