Why does preload throw a circular error?

Scene A preloads Scene B which preloads Scene A. Loading A requires loading B requires loading A — cycle. Switch one of the preloads to a runtime load().

preload() resolves at parse time; the resource is part of the scene's import dependencies. load() resolves at runtime. Use load() to break parse-time cycles.

Should I refactor to remove the cycle?

Yes when possible. Extract shared content into a third scene neither A nor B preload. Or use signals to communicate without direct references.

Fix: Godot 4 preload Circular Reference Error

Quick answer: Switch one preload() to load() to break the parse-time cycle. Or extract shared content into a third scene that neither side preloads.

Scene A’s script has preload("res://b.tscn"); B’s script has preload("res://a.tscn"). Loader can’t decide which to parse first.

The Symptom

Editor or runtime error: “Cyclic reference” or “Resource depends on itself.”

The Fix

# Bad — both preload
var b_scene = preload("res://b.tscn")

# Good — runtime load on one side
var b_scene: PackedScene
func _ready():
    b_scene = load("res://b.tscn")

load() resolves at runtime. By then both scripts have parsed.

Refactor

Better long-term: extract the shared content into a third scene C that neither A nor B preloads. A and B both preload C; cycle gone.

Verifying

Switch preload to load on one side. Editor parses both scenes without error. Runtime loads succeed.

“Break the parse-time cycle. Runtime load. Or extract shared.”

Related Issues

For Godot resource not found, see resource load. For C# Resource references, see references.

Defer with load. Cycle breaks.