Fix: Godot Typed Array Errors in GDScript 2.0

Here is how to fix Godot typed array errors GDScript. GDScript 2.0 introduced typed arrays — a long-requested feature that lets you declare arrays with a specific element type like Array[int] or Array[Node2D]. But the type system around these arrays is stricter than many developers expect, and it leads to confusing errors when you try to assign, pass, or manipulate arrays that look like they should be compatible.

The Symptom

You declare a typed array variable and try to assign a regular array to it. The editor immediately shows a type error, something like:

# Error: Cannot assign a value of type "Array" to
# a variable of type "Array[int]"

Or you have a function that returns a plain Array and you try to store the result in a typed array variable. The script editor underlines the assignment in red, even though the array clearly contains elements of the correct type at runtime.

In other cases, the error appears when you try to append elements. You have an Array[Node2D] and you call append() with what you know is a Node2D, but the value comes from a function that returns a generic Node. The type checker rejects it because Node is not Node2D, even though the actual object is a Node2D at runtime.

You might also encounter this when working with signals, where callback parameters arrive as Variant types and cannot be directly pushed into typed arrays.

What Causes This

GDScript 2.0 performs static type checking at parse time, not at runtime. When you declare var enemies: Array[Enemy], the compiler enforces that every assignment and operation on that variable is provably type-safe based on the declared types alone. It does not look at what the values actually are at runtime.

This means that an Array (untyped) and an Array[int] (typed) are considered different types by the compiler. Even if the untyped array only contains integers, the compiler cannot guarantee that, so it rejects the assignment. This is by design — it prevents subtle bugs where someone adds a String to what was supposed to be an integer-only array.

The same logic applies to inheritance. If a function returns Array[Node], you cannot assign it to an Array[Node2D] variable because the compiler cannot guarantee every element in the Array[Node] is actually a Node2D. Typed arrays in GDScript are invariant, not covariant — meaning Array[ChildClass] is not a subtype of Array[ParentClass].

Functions from the engine API that were written before typed arrays existed often return untyped Array values. Methods like get_children(), get_overlapping_bodies(), and many others return plain arrays even though the elements are of a known type. This creates friction when you try to store those results in typed variables.

The Fix

Step 1: Type your arrays at declaration time. Always declare the type when creating a new array. Do not create an untyped array and try to assign it to a typed variable later.

# Wrong — creates an untyped array, then tries typed assignment
var scores = [10, 20, 30]
var typed_scores: Array[int] = scores  # Error!

# Correct — typed from the start
var typed_scores: Array[int] = [10, 20, 30]

Step 2: Use assign() to convert untyped arrays. When you receive an untyped array from an engine function or external source, use the assign() method to populate a typed array. This performs per-element type checking at runtime.

# Converting an untyped array from get_children()
var children: Array[Node2D] = []
children.assign(get_children())

# This works if all children are actually Node2D.
# It will error at runtime if any child is not Node2D.

Step 3: Cast individual elements when needed. When appending elements from a function that returns a parent type, cast explicitly.

var enemies: Array[CharacterBody2D] = []

# This function returns Array[Node] from the physics system
var bodies = get_overlapping_bodies()

for body in bodies:
    var enemy := body as CharacterBody2D
    if enemy != null:
        enemies.append(enemy)

Step 4: Use typed arrays in function signatures. When you write functions that accept or return arrays, declare the types in the signature. This prevents callers from accidentally passing the wrong array type.

func get_alive_enemies() -> Array[Enemy]:
    var result: Array[Enemy] = []
    for enemy in all_enemies:
        if enemy.is_alive:
            result.append(enemy)
    return result

func apply_damage(targets: Array[Enemy], amount: float) -> void:
    for t in targets:
        t.take_damage(amount)

Why This Works

The assign() method bridges the gap between untyped and typed arrays. Under the hood, it iterates over every element in the source array and verifies each one matches the target type before adding it. This is a runtime operation, which is why the static type checker allows it — the responsibility for type correctness shifts from compile time to runtime.

Typing arrays at creation avoids the problem entirely because the compiler knows the type from the moment the array exists. When you write var scores: Array[int] = [10, 20, 30], the compiler can verify each literal element against the declared type at parse time. No conversion is needed.

The as cast operator performs a runtime type check and returns null if the object is not actually the expected type. By checking for null after the cast, you safely filter out elements that do not match, preventing the runtime error that assign() would throw if an incompatible element were present.

Invariant typed arrays may feel restrictive compared to what you might expect from languages like Java or C#, but they prevent a category of bugs where a supposedly typed array gets contaminated with wrong-type elements through a parent-type reference. The slight inconvenience of explicit conversion is the trade-off for catching type errors early.

Related Issues

If you are seeing type errors related to variables that used to work before upgrading your project, check Fix: Godot Static Typing Errors After Upgrading to 4.x for a broader look at the typing changes. If your typed arrays involve custom classes and you are hitting cyclic reference errors, see Fix: Godot class_name Causing Cyclic Reference Errors. And if your exported typed arrays are not showing up in the inspector, read Fix: Godot Exported Variable Not Showing in Inspector.

Type it when you create it. Convert it when you receive it.