Introduce app-specific error codes to Gitpod

[loujaybee]

Context / Motivation

There are many ways that Gitpod can error. In many cases we are showing raw stack traces, very technical errors to users or in some cases (invalid context URL errors) the workspace and IDE can hang completely. These errors often result in quite scary, red and cryptic looking error messages (e.g. stack traces or internal function call information) and often miss an opportunity to provide guidance to our users about what they can do to fix the error. This is particularly prevalent during workspace start / opening a workspace.

This issue proposes introducing application-specific error codes.

What is an app specific error code?

1. A Gitpod defined string such as project_not_found, auth_no_permission
2. Codes are typically quite coarse-grained so we don't have 100's
3. Codes can be namespaced / prefixed according to our needs (here be dragons 🐉 )
4. The code causing the error might change, but the codes do not
5. Codes are centrally defined in a dictionary (in docs)
6. When new behaviour is added to the product, new codes are considered
7. Codes can be mapped to longer descriptions which describe the error, descriptions live centrally
8. Inside the application, all logic is wrapped, and emit only known error codes
9. If a known error cannot be found, an unknown error code is shown and is tracked and logged

Purpose

The purpose of having application specific error codes is:

1. The key of the error code can be referenced in documentation and error reports
2. The occurrences + frequency of the error can be tracked as a product analytics
3. Any undefined error codes or failure states can be tracked (any errors without an app specific error code)
4. The error code can be used in future audit logs for users or organisations when debugging (without trawling logs)
5. Error code descriptions, and suggested actions can live separate to the application code (e.g. in a CMS) where non-technical individuals can experiment with different messages to users, pointing to relevant documentation pages, or providing different user actions.

Scope

1. Define a technical standard for application specific error codes used throughout Gitpod
2. Define a dictionary (preferably in the public documentation that references each error code, what it means and potential mitigation actions or solutions).
3. Implement minimal first few set of error codes, before gradually rolling out to the rest of the application

Example potential error codes / states

1. invalid_context_url (e.g. #11854)

Example implementations, links and "best practices" / standards

• https://stripe.com/docs/error-codes
• https://auth0.com/docs/libraries/common-auth0-library-authentication-errors
• https://jsonapi.org/format/#error-objects

Example 1	Example 2

Example 3	Example 4

Example 5	Example 6

Example 7

Example 8	-

Relates to:

• https://github.com/gitpod-io/gitpod/issues/8933
• https://github.com/gitpod-io/gitpod/issues/9934
• https://github.com/gitpod-io/gitpod/issues/11199
• https://github.com/gitpod-io/gitpod/issues/3738

[atduarte]

We definitely should improve our error messages. In the process, we would benefit from documenting the failure modes, would get better data about what fails most frequently and would make it easier for support to assign a given issue to a team.

Given the huge effort this would require, I would suggest we start with a 🛹 on a particular part of the system. Even partially improving this for the workspace start would be great. The WebApp side of it might be the easiest first? /cc @jldec

[loujaybee]

Thanks for the input @atduarte 🙏

We would benefit from documenting the failure modes, would get better data about what fails most frequently and would make it easier for support to assign a given issue to a team.

Yup. I think there's an overlap with these issues, also:

• https://github.com/gitpod-io/gitpod/issues/11199
• https://github.com/gitpod-io/gitpod/issues/3738

Given the huge effort this would require

I would suggest we start with a 🛹 on a particular part of the system.

Agree it's a big effort if we are to apply this everywhere. However just to be clear though: the scope of this issue is to implement one or two examples, establish the pattern and then we can roll out and iterate from there.

[Siddhant-K-code]

Error Message, if Gitpod GitHub App is already installed.

Existing User

To Repro this:

• Make Sure, you already have installed the Gitpod GitHub App.
• Go to this endpoint
• Hit Install App & 👀 Error Message

New User Onboarding

It is also painful if a new user is onboarding & configuring for the first time. Here's How?

While Successful registration, this message got pops up.

But, It is kind of an endless loop because the documentation link is on the same page & When you Hit back, there is the same Install App Page:

https://user-images.githubusercontent.com/55068936/212523508-648cb5af-567c-4c79-a475-432040bbce97.mov

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.