Option to use friendlier error messages

[Meorge]

As I've interacted with people just getting into programming (not just Godot), one thing I've often noticed is that people get flustered and confused by the wording in error messages. For example, someone might get the error message:

Error at (10, 9): Identifier "player" not declared in the current scope.

They might be confused by terms like "identifier", "declared", and "scope", and not understand what the (10, 9) means. A more friendly equivalent error message might look like so:

At the 9th character on line 10, you mentioned "player", but I don't know what that is.
To fix this, you'll need to define "player" above line 10 by writing `var player = ...`, or replacing "player" on line 10 with something that references the variable.

While it's longer than the original error message, it may help those new to scripting better understand what's going wrong with their code, and how they could try to fix it. The example here of course isn't a finished draft of what it should show for this type of error message, but hopefully it's at least a starting point for people to understand the idea here. Later on, if people are interested, I could try drafting out more "friendly" versions of error messages from the analyzer.

[Zireael07]

Related to godotengine/godot#42719

[Meorge]

Thanks for linking this! I think the cryptic error messages they're referring to are a step beyond what I was imagining, which was more along the lines of a third level of readability down from the engine's internal errors. But I'll definitely keep this in mind if I run into any more cryptic errors like those! :)

[AThousandShips]

I personally find this far harder to read, for the at the xth character on line y part

For the rest that's an enormous undertaking, making some error messages easier to read is important (and tracked elsewhere) but making error messages give advice is really difficult and generally isn't possible as there's a dozen different things that might be the correct solution and suggesting the wrong solution makes things worse, especially for inexperienced users (who are the ones who would need this IMO)

What if it isn't a local variable but an argument someone spelled wrong? Or what if it's a property in the parent class spelled wrong? Etc.

This would be far more of a general assistant feature and is really hard to accomplish

Further it adds significantly to the burden of translating the editor, which is an important consideration

[AThousandShips]

Related:

• Use AI language models to summarize error messages in the console to facilitate the resolution of bugs #8514
• Add Quick Fix functionality #8004

[Meorge]

I definitely agree with the issue about giving advice - there could be many reasons why player wasn't recognized in the scope, and it'd be very difficult to pin down which one is most relevant to the user at the given moment. Attempting to use AI here, especially for beginners who don't know enough to discern its nonsense from sense, has high potential to go catastrophically wrong, as several people noted in #8514. It's been a while now since I used it, but I recall Rust being well-liked for its descriptive and helpful error messages, and was imagining that Godot could potentially adopt a similar system to appeal to beginners.

My initial proposal for the error message might have been a bit too extensive. 😅 Just something like

On line 10 at the 10th character, you mentioned "player", but I don't know what that is.

might be more appropriate and/or reasonable?

Generally, this is making me wonder if it might make sense for Godot to expose the errors it encounters to outside systems, e.g. plugins, so that they can handle them in more unique ways. This way, people would be able to work on systems like these without impacting the Godot core. Such a feature might be related to issues/discussions like #4111 and #3194.

[AThousandShips]

I think that error message is less readable, I don't see how "I don't know what it is" is any more clear than "isn't declared", it's just more casual, not more clear IMO

[Meorge]

Ah, I think I understand what you mean. Perhaps another alternative solution to this problem would be to keep the original error message, but then provide inline links or a description underneath that explains terms like "scope" for people not familiar with them?

The main concern I'm hoping to address with this issue is newcomers being intimidated by terminology, so providing an easier interface to get familiar with that terminology could help. It also wouldn't hide the "real" error message from them, which means they'd (hopefully) get more comfortable reading them, instead of continuing to rely on simplified versions.

[Mickeon]

I do agree with the sentiment, I really do, but the extra verbosity is a lot more words that non-native speakers have to parse. For people that do understand it, it's a bit... condescending, too?

Having it be an "option" would be a big burden for all contributors involved. There are ways to address this more subtly, a middle ground to make error messages more accessible while still quickly getting to the point.

For the example above, honestly, "declared" could just be "does not exist", as is it what it essentially means:

Error at (10, 9): Identifier "player" does not exist in the current scope.

Overly technical wording in an otherwise simple concept is a bad habit across all of Godot, due to engine contributors being on a "whole other level" compared to actual engine users.

[Meorge]

I agree with your points here. I could definitely see it being condescending to myself, like the engine was "babying" me, as someone who does understand the more technical versions. 😅

Again, my thought was that it would be targeted more at people who are just getting started with programming, similarly to block-coding systems like Scratch. In that context, I think a separately-developed plugin would make more sense than having it built into the engine itself, similarly to how there are beginner-focused block-coding plugins currently being developed for Godot.

This would still require the GDScript analyzer's errors to be exposed to outside code. For the general purposes of plugin flexibility (allowing plugin devs to extend and customize the engine as much as possible without needing to use custom builds), I could see this being a useful addition, although I also understand it may not be a very high-priority item.

Looking at gdscript_analyzer.cpp and the rest of the codebase, it doesn't look like there is support for localizing the error strings there (i.e., the strings are hard-coded into the analyzer, and don't appear elsewhere in the project such as for translation tables). If localization/translation support for error messages were to be added, it could benefit non-English-speaking Godot users. Because it would likely require moving the location of converting error message codes to actual strings to elsewhere in the engine, the plugin support could "piggyback" on that, so to speak.

[Mickeon]

it doesn't look like there is support for localizing the error strings there (i.e., the strings are hard-coded into the analyzer, and don't appear elsewhere in the project such as for translation tables)

Lack of support for these strings seems like an oversight. There are very few error strings out there that are localized just fine, and I do believe all errors for the shader language are localized as well(?).

[dalexeev]

I agree that we should improve specific error messages and perhaps the format in general, as long as it does not hurt both novice and advanced users.

For example, if you find Error at (10, 9) confusing, we could replace it with a more verbose Error at line 10 column 9. However, note that we already use a similar short notation:

Consider that conciseness has its advantages as well as disadvantages. Short messages allow you to spend less time recognizing the error, while more detailed and friendly errors can be annoying because you have to spend more time to extract the error meaning.

There was also a discussion about assigning numeric/string identifiers to GDScript errors, but I couldn't find it. This is important if we want to add localization to error messages.

If we add something like this in the future, I think the error should consist of two parts: a short description with technical terminology that may be unclear to beginners, and details that describe the essence of the error and its possible causes in more understandable language. We could do it like in Firefox debugger: add a Learn More / Help / Details button and when clicked, open a website / Editor Help page with details about the error.

MDN - ReferenceError: "x" is not defined

This would also help to avoid misunderstanding. When you read about an error on a website, you are more likely to guess that these are abstract examples, rather than a recipe for fixing your specific error. I think we should be careful about trying to educate the user or give them advice in the error description directly. Often we do not have enough context and the compiler is not smart enough to give useful advice. It's bad when we give useless advice, and very bad when we give misleading advice.

Let me demonstrate this in more detail. When you try to help someone, you usually do the following steps:

1. What went wrong? This is the only step that the compiler understands, but without context. False positive cascading errors are still possible here, especially parser errors. Often, subsequent errors will go away if you fix another error higher in the script or in a dependency. Suggesting to fix a cascading error can be totally harmful.
2. Why did this happen? The same error manifestation can be caused by different reasons. For example, the undeclared identifier error can be caused by a missing declaration, a typo, or something else. It's difficult to list all the possible cases, let alone automatically determine the cause. Our goal is not just to shut the compiler up, but to find the real cause.
3. How ​​to fix it? Each cause has its own way to fix it. Without doing the second step, we cannot proceed to the third.
4. How ​​to avoid similar mistakes in the future? A good teacher doesn't just point out the mistake and how to fix it, but also tells you more useful information. We could provide links to related documentation sections, at most.

So I think that only point 1 can be detected more or less reliably and should be displayed in the error message. Points 2-4 are more material for a website or a new help page.

[Calinou]

For example, if you find Error at (10, 9) confusing, we could replace it with a more verbose Error at line 10 column 9.

I've opened a PR for that: godotengine/godot#95842