[Proposal] Error classes, components, and codes

[CPTNB]

Problem Statements

1. As a plugin author I lack the context and mental energy to handle and present errors myself
2. As an end user, I want to have a consistent, predictable UX for error cases
3. As an end user, developer, and administrator, I want to be able to google errors and see resolutions on Stack Overflow, blogs, and OpenSearch documentation.

Solution

Problems 1 and 2 should be solved with a component library for errors, problem 3 is solved with error codes. Error codes are most useful if they're presented in a consistent way, so codes require 1 and 2 to be solved.

Error Classes

I want to be able to, at any point in the stack, receive/create/pass objects that represent errors I can work with predictably.

Must haves:

• Simple constructors so that anyone, from any context can create them
• Be (de)serializable so they can be passed across the network boundary and persisted

Nice to haves:

• Support runtime branching:
  (error: NewOSErrorClass | any) => isErrorType(error, MySpecialError) ? doThing() : doOtherThing()
  If we could do something with TS discriminated unions that would be sick
• Flexible interface: Since most errors won't be these new classes, we need all the APIs for the new error classes to seamlessly take pretty much anything and be callable idempotently

Error Components

I want to have a component library that displays errors. EUI already has some "error-y" components and treatments, but I want something dead simple--a set of maybe 4-5 components that will take an error (or any value) and render it.

For example, these components might be:

• PageContentError (for when a large portion of the app can't be rendered)
• BannerError (for when you want to notify something is broken)
• InlineError (when, say, the contents of a dropdown can't be loaded)
• IconError (when, say, certain elements in a list have errored in a way that doesn't block normal operation)

These components would do the smart thing when stack traces, error codes, messages, debug information, etc. are or are not available.

The ideal API would look something like this:

async function foo () {
  try {
    return MyComponent(myWorkItem);
  } catch (error) {
    return InlineError(error);
  }
}

Error Codes

Error codes should be:

• namespaced to the plugin (including core plugins)
• compatible with back-end sourced codes (including non-OpenSearch back-ends)
• useful google search input
• Ideally, unique to each error origination point

Suggested Implementation

• A new core plugin "errors" that has these classes and components
• A schema for error codes
• Nice to have: some piece of technology that builds out error classes for you
• Nice to have: CR process tweaks that make sure error branches have codes attached

Out of scope: Error Handling

It'd be nice to work on error handling, but for this I'm only looking at being able to identify and display errors.

Additional context

React does error codes very well, where codes link back to the react documentation. I'd like if we can do something like that eventually, but for now the low-hanging fruit is google-ability and display-ability.

[CPTNB]

Note: some back-end timeouts (long query, etc.) manifest to the end user as a 403. This is confusing and makes the product harder to support and troubleshoot. As part of this work we should adhere to HTTP status code standards.

[dblock]

This problem comes up way too often in our managed service where users are confused, then the Engineer debugging a problem gets confused, and we get back to this again and again. Would someone care to contribute a fix for just the timeout leading to a 403 part of the problem? cc: @seanneumann

I opened #2320 for that specific issue.

[joshuarrrr]

Other examples of confusing errors:

• [BUG] Setting override_main_response_version to true on OS triggers error in dashboards #687
• [BUG] Can't see any field in Discover page: just the "_source" one #1117

[KrooshalUX]

As I am working through developing error handling guidance through the lens of the design system, I am wondering if we can formalize some next steps here.
What would be helpful, though I am not sure if its a practical ask, is to get an audit of all of the handled errors to start.

From there I imagine we might :

• Evaluate that these errors are being presented to the end user with the correct UI
• Work with docs team to re-write the returned errors
• Create an error code documentation page
• Add the edited error handling language to the design system guidance

Does this sound actionable? Is there a reasonable way to get a dump of the handled errors, and potentially identify which errors are not yet handled but we would like to get these accounted for?

@kavilla @joshuarrrr

[joshuarrrr]

@KrooshalUX I like this idea, although I think it's a significant amount of work. Some errors are relatively easy to find and extract from the code, but others that dynamically bubble through multiple components will be harder to track down. For point 1, how we present them in the UI, an audit may be the first step, but some automated test tooling may have even broader long-term impact.

Do you see this audit effort as part of OUI compliance, or as a follow-up to the current wave of work we're doing in #4111?

[joshuarrrr]

Another error UI improvement I was thinking about - when an action is not permitted because of some user-controlable setting, ideally the error message would deep link to the appropriate advanced setting: see #3961 (comment)

[KrooshalUX]

@joshuarrrr Great question - I consider this part of the Design System compliance (establishing the patterns), not quite OUI compliance (using components to implement the patterns). This would also be an effort across OSD & all plug-in features to do the audit. If there is any way we can start with the base of OSD, that would be a great first step in helping the Design System establish standards for these error handling patterns.

[KrooshalUX]

Another error UI improvement I was thinking about - when an action is not permitted because of some user-controlable setting, ideally the error message would deep link to the appropriate advanced setting: see #3961 (comment)

Possibly, there are cases where users wont have control over advanced setting, so sending them there isnt always useful / could be more frustrating.

This would fall in the bucket of establishing a pattern of handling permission errors.