# try

Learn how to handle errors in template execution.

This action wraps actions with error handling, similar to a try/catch/finally block.

If the action fails, the `else` branch runs as a fallback. The `finally` branch always runs regardless of the outcome. When there is no `else` branch, use `help` to enrich the error message with suggestions and links.

## Example

The following template attempts an action that always fails and handles the error gracefully:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Error handling",
  "description": "Demonstrates error handling with try.",
  "actions": [
    {
      "name": "try",
      "action": {
        "name": "fail",
        "message": "Something went wrong."
      },
      "else": {
        "name": "print",
        "semantics": "warning",
        "message": "The action failed, but we recovered."
      },
      "finally": {
        "name": "print",
        "message": "Done."
      }
    }
  ]
}
```

To apply this template, run:

```sh
croct use template.json5
```

### Custom help

When there is no `else` branch, use [`help`](#help-prop) to provide context for the error:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Dependency checker",
  "description": "Checks for required dependencies.",
  "actions": [
    {
      "name": "try",
      "action": {
        "name": "check-dependency",
        "dependencies": [
          {"name": "next"}
        ]
      },
      "help": {
        "message": "This template requires a Next.js project.",
        "suggestions": [
          "Create a new Next.js project and try again."
        ],
        "links": [
          {
            "label": "Next.js docs",
            "url": "https://nextjs.org/docs"
          }
        ]
      }
    }
  ]
}
```

If the dependency check fails, the custom message, suggestions, and links are displayed instead of the raw error.

## Properties

These are the supported properties:

- `name`: `string`

  The action identifier. Always `try` for this action.

- `action`: `Action | Array<Action>` (see [Action](/reference/cli/templates/actions), [Array\<Action>](/reference/cli/templates/actions))

  The actions to attempt.

  Accepts a single action or a list of actions.

- `else`: `Action | Array<Action>` (optional) (see [Action](/reference/cli/templates/actions), [Array\<Action>](/reference/cli/templates/actions))

  The fallback actions to execute if the primary action fails.

  Accepts a single action or a list of actions. When provided, `help` is ignored.

- `finally`: `Action | Array<Action>` (optional) (see [Action](/reference/cli/templates/actions), [Array\<Action>](/reference/cli/templates/actions))

  The actions to execute after completion, regardless of whether the primary action succeeded or failed.

  Accepts a single action or a list of actions. This branch runs even if `else` also fails.

- `help`: `object` (optional)

  Custom error context displayed when the action fails and no `else` branch is provided.

  If the action fails and neither `else` nor `help` is set, the original error is thrown as-is.

  - `message`: `string` (optional)

    A custom error message replacing the original one.

  - `suggestions`: `Array<string>` (optional)

    A list of suggestions to help resolve the issue.

  - `links`: `Array<object>` (optional)

    A list of links with additional information.

    - `label`: `string`

      The display text for the link.

    - `url`: `string`

      The URL to link to.

## Explore

- [Fail](/reference/cli/templates/actions/fail): Learn how to abort with an error message.
- [Test](/reference/cli/templates/actions/test): Learn how to branch based on conditions.
- [Run](/reference/cli/templates/actions/run): Learn how to run a group of actions that may fail.
- [Print](/reference/cli/templates/actions/print): Learn how to print a fallback message on error.