Exception handling (try catch) in gdscript

[Gnumaru]

Describe the project you are working on

A 2d platformer

Describe the problem or limitation you are having in your project

none

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The title is a clickbait. I DO NOT propose adding try-catch to gdscript. I would merely like to discuss alternatives.

It has already been stated that try-catch will never come into gdscript. I'm perfectly fine with that.

godotengine/godot#3516

However, I would like to discuss with other users if there is another way of making life easier for those that need to deal with a lot of error handling. This "making life easier" could or could not involve changes to gdscript.

Currently gdscript encourages usage of int error codes for error handling. So, a user that has a series of function calls that need to be checked can make it this way:

# EXAMPLE 1
var error_code:int
error_code = func1()
if error_code:
	return error_code
error_code = func2()
if error_code:
	return error_code
error_code = func3()
if error_code:
	return error_code

The ifs can become single liners

# EXAMPLE 2
var error_code:int
error_code = func1()
if error_code: return error_code
error_code = func2()
if error_code: return error_code
error_code = func3()
if error_code: return error_code

And let's not forget that gdscript supports semicolons

# EXAMPLE 3
var error_code:int
error_code = func1(); if error_code: return error_code
error_code = func2(); if error_code: return error_code
error_code = func3(); if error_code: return error_code

If I'm not mistaken, that's the limit with current gdscript.

Try-catch will never come. That's okay. If it did come, it could be like this

# EXAMPLE 4
try:
	func1()
	func2()
	func3()
except err:
	return err

But it will never come, and that's totally fine.

So, what can be done to make the user experience more pleasant, similar to a try-catch?

Perl 5 has an interesting concept called "default variable". It is a local variable that is already declared in any context. Functions with apparently discarded return values instead have the return values assigned to the default variable. And single parameter functions called without the parameter actually use the default variable as argument.

If gdscript had a perl like default variable named _ (underscore), or any other name, like _default, we could rewrite example 3 like this:

# EXAMPLE 5
func1(); if: return
func2(); if: return
func3(); if: return

The if without an expression uses the default variable, and the return without value uses the default variable also.

But whe could go further and create a new language construct, a pseudo-function called catch(), that would be replaced by the parser with "if _default: return _default". If this pseudo-function existed, we could rewrite example 5 like this

# EXAMPLE 6
func1(); catch()
func2(); catch()
func3(); catch()

or like this

# EXAMPLE 7
func1()
catch()
func2()
catch()
func3()
catch()

or maybe catch() could receive the function call as argument, so example 6 could be rewritten like this:

# EXAMPLE 8
catch(func1())
catch(func2())
catch(func3())

since the function return values are being stored in the default variable, the value can be reused in a chain of function calls

# EXAMPLE 9
catch(func1())
catch(func2(_default)) # here _default contains the return value of func1()
catch(func3(_default)) # here _default contains the return value of func2()

But since in perl a missing function parameter uses the default variable, writing the _default as parameter for func2() and func3() would be optional.

I know that a real exception handling system would be complex, since an exception could be thrown anywhere in a code block, like in a nested function call

# EXAMPLE 10
func1(func2(func3(func4())))

But leveraging code replacement, we could implement a poor man's try-catch using the parser alone, with the limitation that it would only "catch" exceptions in "root" statements, not in nested ones.

So, a poor man's try-catch would be written like this

# EXAMPLE 11
try:
	func1()
	func2()
	func3()

and would be transpiled to the manual error handling scheme

# EXAMPLE 12
var error_code:int
error_code = func1()
if error_code:
	return error_code
error_code = func2()
if error_code:
	return error_code
error_code = func3()
if error_code:
	return error_code

Without a catch block, without finally, just a try without catch.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

already described above

If this enhancement will not be used often, can it be worked around with a few lines of script?

already described above

Is there a reason why this should be core and not an add-on in the asset library?

already described above

[Calinou]

Related to #3194.

[me2beats]

see also
godotengine/godot#7643
godotengine/godot#3516

it looks like in 16 Juan said that this will not happen, but many years have passed and gdscript is now rewritten to 2.0 :))

[nonunknown]

well I think this can be already done with godot 4, since Callables are implemented you can create a func catch(method:Callable) and deal with that in the created function!

[dalexeev]

You can take advantage of the fact that AND and OR operations are lazy:

func func1():
    print(1)
    return OK

func func2():
    print(2)
    return ERR_CANT_OPEN

func func3():
    print(3)
    return ERR_ALREADY_EXISTS

func _run():
    func1() or func2() or func3()

# Prints:
# 1
# 2

A little longer, but in my opinion a more idiomatic version:

func1() == OK and func2() == OK and func3() == OK

There are also other options, for example, as written above, there is Callable (which have bind method). You can write your own function that will allow you to shorten the code if some fragment is often repeated.

However, I don't see the problem in Example 1: repetition is not always bad. It is bad when large pieces of code are repeated in different parts of the application. When 1-2 lines are repeated next to each other (as in your example) - this is a common thing, there is nothing to fix here. Unless you can use the following option, it is shorter:

var err = func1()
if not err:
    err = func2()
if not err:
    err = func3()
return err

Personally, I really dislike exceptions, in my opinion they cause much more problems than a few extra lines of code. Exceptions are based on the vicious idea of deferring error handling until later, somewhere up the call stack. Exceptions break the order of program execution and require tracking of potentially the entire graph of application function calls.

I prefer return codes or compound return results (with an error status).

[Kelin2025]

I might sound rude, so apologies for that, but can someone in Godot team elaborate (or share the link if already elaborated) why they are against try/catch, except the "images folder" analogy (that's basically a faulty generalization) and weird takes like "better crash than handle bad code"?
Tbh writing utility libraries or creating complex abstract logic becomes a huge pain without it.
We already have Go lang, do we really want to repeat "if err != nil everywhere" story? Do we really want to rely on handmade error codes instead of having built-in entity for that? Do we really want to sacrifice debugging opportunities as well (e.g. automatically seeing custom exceptions without doing handmade loggers)? If so, why do we have signals then, they could be hand-made as well?
Also, I came across the issues and saw a lot of people that'd like to see it in GDScript, but their issues were just closed with "never gonna happen"-like answers. Godot is advertised as community-driven. So why this feature request is being strongly ignored for like 7 years?

[dalexeev]

Go at least can return two variables so it's at least type-safe and not that bad in terms of syntax.

See these proposals:

• Add support for returning multiple values from a function #6684
• Add typed tuples to GDScript #2944
• Add union types to Typed GDScript #737
• Add compact and customizable complex Struct types to Variant with a strong, but lightweight type system #2816
• Add pass-by-value structs to GDScript #5130

You can already write a Result class extending Resource/RefCounted/Object with error/error_code, error_message and data properties. Or these properties and methods may be part of a utility class dedicated to this operation. And in many cases you don't even need that, since you can use null as a failure indicator. And also use bool or error codes.

I see no advantage in this code

func _on_file_selected(path: String) -> void:
    var importer := Importer.new()
    try:
        importer.import(path)
        set_data(importer.result)
    except e:
        show_popup(e.message)

over this

func _on_file_selected(path: String) -> void:
    var importer := Importer.new()
    importer.import(path)
    if importer.error:
        show_popup(importer.error_message)
    else:
        set_data(importer.result)

But exceptions allow you to defer error handling up the call stack. And I think that this is a disadvantage, not an advantage. I can explain in more detail why I think so, I have several arguments. But it takes time and I'm not sure it's worth doing in this discussion.

[Kelin2025]

The issues you mentioned are about types. And although stuff like "union types", "object types" is cool, it will cover only a portion of error cases. And I don't expect GDScript type system to become something like TypeScript, it's too complex

Also, given that maintainers have been repeatedly using "it introduces complexity on implementing, maintaining etc" as an argument, just adding exceptions is no way near "complex" as implementing all of the above

Any mature language has either exceptions or a strong type system to minify the amount of places where it can go wrong. At least one of them.

Either be strict or let the developer do it for themselves. GDScript does neither.

Moreover, type system is not a complete replacement for the exceptions. There's stuff that isn't covered by types:

• API requests. If some server changes its response structure, type system won't save you. And it might be broken in a way that you'll know way later
• Production logging. If some user gets an unexpected crash, I'd like to see why did it happen. I'd like it to automatically send the report with a place where error happened. But we can't have tools like https://sentry.io/welcome/ , because they intercept exceptions
• Conditions that aren't related to types. For example, param > 0 can also be a strict requirement. Type system doesn't cover it

[Kelin2025]

I see no advantage in this code

First of all, this story isn't only about try/catch, but about the concept of exceptions first

Like I mentioned earlier, take a look at this snippet:

@onready var damage_dealer := $DamageDealer
@onready var hit_area := $HitArea
@onready var cooldown := $Cooldown

func declare_action():
  return HitAreaPreset.new({
    damage_dealer: damage_dealer,
    hit_area: cooldown <-
  })

Yes, you sent a couple of issues related to this case, but I already answered it above

We cannot type annotate objects now. But hit_area: cooldown is the same as trying to do global_position = "foo" or 2.call_non_existing_thing(). It's a wrong code

I could just throw in HitAreaPreset constructor and it'd automatically open a place in IDE where did that happen, with all the useful information. Instead, it will crash way later and produce an absolutely useless trace (because it crashed 10 steps after the actual mistake is made)

if error: won't help here. if error doesn't let IDE know if that's an error. It's only a crutch to avoid crash. We should not avoid it here

Most of the time I have to run the game and manually check if everything works fine. And if it fails, it takes a lot of time to debug. Just because we can't explicitly say to "throw here". Good luck searching through 100 perks with 150+ lines of code each

---

What about try/catch - try less trivial examples then. Introduce several conditions where it might fail. Like I said, check out Go lang and see how verbose the code with if/else approach is

[dalexeev]

Like I mentioned earlier, take a look at this snippet:

I don't understand what you see as a problem in this example. Either you use static types in the constructor (_init(damage_dealer: Combatant, hit_area: Area2D) -> void) and GDScript checks for this, or you manually check the passed parameters in the constructor (if you don't use static types or if the type system doesn't check this, as is the case with dictionary keys).

Instead of throwing an exception, there should be an assert/breakpoint (if the error is not expected in release builds), an error/warning output to the console/log using push_warning/push_error, a call to the "panic" function (if the error is fatal) or something else. So at least you will not miss an error during development and will be able to see the call stack, variable values and other information in the debugger. In release builds, a lot of this also works (output to the console and user://logs/), but you won't be able to get the call stack for performance reasons.

If you need to recover from an error, then the method should return the success status of the operation, and the caller should process the returned result. I already wrote about this above.

API requests. If some server changes its response structure, type system won't save you. And it might be broken in a way that you'll know way later

You should assume that an HTTP request may return a response with an incorrect data structure and check its validity before proceeding, rather than trying to perform actions with an unknown structure by wrapping everything in a try. To simplify structure validation, you can use validators such as JSON Schema.

Production logging. If some user gets an unexpected crash, I'd like to see why did it happen.

This can be implemented without exception. Console output is also logged in release builds by default. You can see information about the crash of the engine in the console, but it is not logged in user://logs/ (probably this can be fixed).

Conditions that aren't related to types. For example, param > 0 can also be a strict requirement. Type system doesn't cover it

If the type system does not cover something, you should check it yourself. I have listed the main options above.

if error: won't help here. if error doesn't let IDE know if that's an error. It's only a crutch to avoid crash. We should not avoid it here

I agree that you should not mask/hide the error, but I did not suggest doing so. In the examples below, you can somehow see that something went wrong.

Options

# Only debug builds.
func do_something(param: int) -> SomeObject:
    assert(param > 0)
    return _do_something_unsafe(param)

# Logging to console and "user://logs".
func do_something(param: int) -> SomeObject:
    if param <= 0:
        push_error("param must be > 0")
        return null
    return _do_something_unsafe(param)

# Compound return result.
func do_something(param: int) -> Result:
    if param <= 0:
        return _make_error("param must be > 0")
    return Result.new(_do_something_unsafe(param))

# Fatal error.
func do_something(param: int) -> SomeObject:
    if param <= 0:
        App.fatal("param must be > 0")
        return null
    return _do_something_unsafe(param)

[dalexeev]

I could just throw in HitAreaPreset constructor and it'd automatically open a place in IDE where did that happen, with all the useful information. Instead, it will crash way later and produce an absolutely useless trace (because it crashed 10 steps after the actual mistake is made)

[Gnumaru]

I've stated at the top that "The title is a clickbait. I DO NOT propose adding try-catch to gdscript. I would merely like to discuss alternatives."

If gdscript had type unions and a native Exception variant, we could write things such as:

func get_someone()->Node|Exception:
	var node:Node = get_node_or_null('../some/node')
	if node != null: return node
	return Exception.new('node not found')

func other_func()->void|Exception:
	var node:Node|Exception = get_someone()
	if node is Exception: return Exception.new('I needed some node that was not found')
	node.do_something()

Wich whould help a lot in implementing and using methods that may or may not suceed as expected.

Type unions could be implemented with type erasure, so that they would only validate at compile time, but the runtime would use just Variant, wich wouldn't need any change in the runtime, only in the gdscript parser/compiler.

There is already an older proposal with 98 positive reactions about type unions:

#737