azure-cli/doc/error_handling_guidelines.md

# Azure CLI Error Handling Guidelines

This document aims to provide the guidelines for command group authors to onboard the error handling method and the new error output format.

Previously in Azure CLI, `CLIError` was widely used to wrap error messages after different kinds of error types are being caught. Now, `CLIError` is deprecated and replaced by a set of newly designed error types, which will provide clearer structures for error categorizing and also more actionable error outputs for better user experience.

For the new commands or features authoring in CLI modules, here are what need to be done to get onboard. __Any PRs not following these rules here will be rejected.__ For the existing `CLIError` in command groups, command group owners should schedule to replace them with the new error types.
1. [__Mandatory__] Use the newly designed error types instead of `CLIError`. See section [Error Type](#Error-Type)
2. [__Mandatory__] Follow the error message authoring guidelines. See section [Error Message](#Error-Message)
3. [__Recommended__] Provide recommendations for users to take action. See section [Error Recommendation](#Error-Recommendation)

__For CLI extensions, it's optional to adopt the new error types. If applying the new error types,  `azext.minCliCoreVersion` should be set to `2.15.0` or higher versions.__

## Error Type

### Available Error Types

The newly designed error types are provided in [azure/cli/core/azclierror.py](https://github.com/Azure/azure-cli/blob/dev/src/azure-cli-core/azure/cli/core/azclierror.py), where the error types are defined in three layers with their structures shown below. `AzCLIError` is the base layer for all the newly defined error types. The second layer includes the main categories (`UserFault`, `ClientError`, `ServiceError`), which can be shown to users and also can be used for Telemetry analysis. __The third layer includes the specific error types, which are the ones command group authors can use when raising errors.__

```
| -- AzCLIError                             # [Base Layer]: DO NOT use it in command groups
|    | -- UserFault                         # [Second Layer]: DO NOT use it in command groups
|    |    | -- CommandNotFoundError         # [Third Layer]: Can be used in command groups
|    |    | -- UnrecognizedArgumentError
|    |    | -- RequiredArgumentMissingError
|    |    | -- MutuallyExclusiveArgumentError
|    |    | -- InvalidArgumentValueError
|    |    | -- ArgumentUsageError               # fallback of argument related errors
|    |    | -- BadRequestError
|    |    | -- UnauthorizedError
|    |    | -- ForbiddenError
|    |    | -- ResourceNotFoundError
|    |    | -- AzureResponseError               # fallback of response related errors
|    |    | -- AzureConnectionError
|    |    | -- ClientRequestError               # fallback of request related errors
|    |    | -- ValidationError                  # fallback of validation related errors
|    |    | -- FileOperationError
|    |    | -- ManualInterrupt
|    |    | -- UnclassifiedUserFault            # fallback of UserFault related errors
|    |    | -- InvalidTemplateError
|    |    | -- DeploymentError
|    | -- ClientError
|    |    | -- CLIInternalError
|    | -- ServiceError
|    |    | -- AzureInternalError
```

To summarize, here is a list of rules for command group authors to select a proper error type.
- __DO NOT__ use the error types defined in the base layer and the second layer
- Avoid using the fallback error types unless you can not find a specific one for your case
- Consider defining a new error type if you can not find a proper one when it is a general error

### Apply the Error Type

Applying the new error types is just as easy as using `CLIError`. Wherever an `CLIError` could appear, you can use the new error types to replace it.

For example, previously, you may raise `CLIError` in this way.
```Python
err_msg = 'the specified resource group ... not exist'
raise CLIError(err_msg)
```

Now, you could use the new error type in this way.
```Python
from azure.cli.core.azclierror import ResourceNotFoundError

err_msg = 'the specified resource group ... not exist'
raise ResourceNotFoundError(err_msg)
```

The new error types all have the same signature for `__init__` function shown below. When an error is raised, you are highly recommended to provide some recommendations for users to take action if the error message is not clear enough for users to know what to do next.
```Python
__init__(self, error_msg, recommendation=None):
```
- `error_msg`: _string_, _required_. A clear message shown to users what the error is.
- `recommendation`: _string_ or _list_, _optional_. Recommendations telling users what action to take.

### Add a New Error Type

If there is not a proper error type for your case and the error is general enough, consider defining a new error type in [azure/cli/core/azclierror.py](https://github.com/Azure/azure-cli/blob/dev/src/azure-cli-core/azure/cli/core/azclierror.py). The defined error type should inherit from one of the errors defined in the second layer (`UserFault`, `ClientError`, `ServiceError`). Please reach out to AzCLIDev@microsoft.com for more details before adding a new error type.

For example, a new error type can be defined in this way.
```Python
class NewErrorTypeName(UserFault):
    """ A description of new error type. """
    pass
```


## Error Message

A clear and actionable error message is very important when raising an error, so make sure your error message describes clearly what the error is and tells users what they need to do if possible.

A general pattern is provided here, keep it in mind when you write an error message.

1. __What the error is.__
2. __Why it happens.__
3. __What users need to do to fix it.__

Below are the specific DOs and DON'Ts when writing the error messages. PRs violate rules here will be rejected.

__DOs__
- Use the capital letter ahead of an error message.
- Provide actionable message with argument suggestion. (e.g., Instead of using `resource group is missing, please provide a resource group name`, use `resource group is missing, please provide a resource group name by --resource-group`)

__DON'Ts__
- Do not control the style of an error message. (e.g., the unnecessary `'\n'` and the colorization.)
- Do not include the error type info in an error message. (e.g., `usage error: --ids | --name [--resource-group]`)
- Do not use a formula-like or a programming expression in the error message. (e.g., `Parameter 'resource_group_name' must conform to the following pattern: '^[-\\w\\._\\(\\)]+$'`)
- Do not use ambiguous expressions which mean nothing to users. (e.g., `Something unexpected happens.`)


## Error Recommendation

When necessary, it is highly suggested for command group authors to provide recommendations for users to resolve the errors they encountered. It is also suggested that we split the error message itself from the recommendations, which can be done either by specifying the `recommendation` parameter when initiating an error type or using the `set_recommendation` function after an error is initiated. In both cases, you can either provide a single recommendation with a string or multiple recommendations with a string list. The recommendations you provide will be printed right below the error message, one recommendation in a new line.


```Python
from azure.cli.core.azclierror import MutuallyExclusiveArgumentError

error_msg = 'Please specify all of (--publisher, --offer, --sku, --version), or --urn'
recommendation = 'Try to use --urn publisher:offer:sku:version only'
raise MutuallyExclusiveArgumentError(err_msg, recommendation)
```

```Python
from azure.cli.core.azclierror import MutuallyExclusiveArgumentError

error_msg = 'Please specify all of (--publisher, --offer, --sku, --version), or --urn'
recommendation = 'Try to use --urn publisher:offer:sku:version only'

az_error = MutuallyExclusiveArgumentError(err_msg)
az_error.set_recommendation(recommendation)
raise az_error
```