Fix: Godot ResourceLoader.load_threaded_request Not Completing

Here is how to fix Godot 4 ResourceLoader.load_threaded_request that fires off a load and never finishes. You request a heavy scene asynchronously, expecting to swap to the next level a few seconds later, and the status forever returns THREAD_LOAD_IN_PROGRESS. Threaded loading in Godot is cooperative: the loader needs the main thread to poll status to advance.

The Symptom

You call load_threaded_request("res://world.tscn") in _ready. A few frames later you call load_threaded_get_status and get IN_PROGRESS. You wait longer; still IN_PROGRESS. The CPU is mostly idle. The load never completes.

What Causes This

Status not polled. The loader uses status calls as cooperative checkpoints. Without polling, the worker thread can stall waiting for the main thread to confirm progress.

Wrong path or already-loaded resource. If the path is wrong, status returns INVALID_RESOURCE. If the resource is already in cache, the loader may complete instantly with no IN_PROGRESS phase.

Sub-resource cycle. Concurrent threaded loads of overlapping resource trees can deadlock when both try to load the same sub-resource.

Main thread starved. If _process runs heavy work (large scripts) and rarely yields, the loader has no opportunity to make progress.

The Fix

Step 1: Poll status every frame.

extends Node

var path := "res://levels/world.tscn"
var progress := []

func _ready():
    ResourceLoader.load_threaded_request(path)

func _process(_delta):
    var status = ResourceLoader.load_threaded_get_status(path, progress)
    match status:
        ResourceLoader.THREAD_LOAD_IN_PROGRESS:
            $LoadingBar.value = progress[0] * 100
        ResourceLoader.THREAD_LOAD_LOADED:
            var scene = ResourceLoader.load_threaded_get(path)
            get_tree().change_scene_to_packed(scene)
            set_process(false)
        ResourceLoader.THREAD_LOAD_FAILED:
            push_error("Load failed")
            set_process(false)

The progress array carries fill ratio in slot 0. Use it for a smooth loading bar.

Step 2: Use await for cleaner code.

func load_async(p: String) -> Resource:
    ResourceLoader.load_threaded_request(p)
    while true:
        var status = ResourceLoader.load_threaded_get_status(p)
        match status:
            ResourceLoader.THREAD_LOAD_LOADED:
                return ResourceLoader.load_threaded_get(p)
            ResourceLoader.THREAD_LOAD_FAILED, ResourceLoader.THREAD_LOAD_INVALID_RESOURCE:
                return null
        await get_tree().process_frame

Step 3: Handle invalid paths.

if not ResourceLoader.exists(path):
    push_error("Resource missing: " + path)
    return
ResourceLoader.load_threaded_request(path)

Step 4: Avoid concurrent loads of overlapping trees. If world.tscn includes player.tscn, do not threaded-load both at the same time. Load world; the world scene will pull in player as a dependency on the same load.

Step 5: Yield from heavy main-thread work. If your _process does multi-millisecond work, sprinkle await get_tree().process_frame in long loops so the threaded loader can advance status:

for i in 10000:
    do_some_work(i)
    if i % 100 == 0:
        await get_tree().process_frame

Sub-Threads And Use Sub-Threads Flag

Pass use_sub_threads = true to load_threaded_request for very large resource trees. The loader spawns sub-worker threads to load sub-resources in parallel. Beware: more parallelism does not always mean faster loads, especially for I/O-bound work on slow disks.

ResourceLoader.load_threaded_request(path, "", true)

“Threaded loads are cooperative. Poll status every frame, await between heavy work, and the worker advances.”

Related Issues

For Godot resource preloader issues, see Resource Preloader Not Preloading. For preload null returns, see Preload Not Finding Nested Resource.

Poll every frame. Pass progress array. Await between heavy work. Loads finish.