> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/3.0/deployment-entities/environment/failure-strategy.md).

# Failure strategy

Configure what Harness does when an environment or infrastructure fails to resolve, independently of the stage failure strategy.

An environment-level `on-failure` rule controls what Harness does when a failure occurs while resolving an environment or its infrastructure, independently of the stage failure strategy. Before this rule existed, a failure while resolving the environment fell through to the stage `on-failure` rule, the same as any other failure, with no way to react to it differently.

Unified does not have a separate execution node for the environment itself. An environment failure surfaces on the Infrastructure node, so that is where Harness evaluates the environment rule and records retries.

***

## YAML

Add `on-failure` next to `items` under `environment`. `on-failure` is a list of rules, each with an `errors` list and an `action`:

```yaml
environment:
  items:
    - id: production
      deploy-to: production-cluster
  on-failure:
    - errors: [all]
      action: stage-rollback
```

An environment rule only reacts to a failure while Harness resolves the environment or its infrastructure. It does not catch failures in the steps under `steps:`, or in rendering, templating, or resource-lock, which always use the stage `on-failure` rule.

***

## What you will learn

* Which actions are allowed on an environment, and which are rejected
* How the environment rule and the stage rule interact
* How to configure retry on an environment
* How `on-failure` behaves when you deploy a list of environments

***

## Actions

| YAML value             | Allowed on an environment | What happens                                                                           |
| ---------------------- | ------------------------- | -------------------------------------------------------------------------------------- |
| `abort`                | Yes                       | Abort the pipeline immediately.                                                        |
| `fail`                 | Yes                       | Mark the stage as failed and stop the pipeline.                                        |
| `pipeline-rollback`    | Yes                       | Trigger rollback across all stages in the pipeline.                                    |
| `retry`                | Yes                       | Re-run environment or infrastructure resolution up to a configured number of attempts. |
| `stage-rollback`       | Yes                       | Trigger the stage's rollback steps.                                                    |
| `ignore`               | No                        | Rejected.                                                                              |
| `success`              | No                        | Rejected.                                                                              |
| `proceed-with-default` | No                        | Rejected.                                                                              |
| `manual-intervention`  | No                        | Rejected.                                                                              |
| `retry-step-group`     | No                        | Rejected.                                                                              |

`stage-rollback` is allowed on an environment but not on a service, because by the time an environment or infrastructure fails to resolve, the stage may already have deployed steps to roll back.

`abort`, `fail`, `pipeline-rollback`, and `stage-rollback` can be written as a bare string, the same way the Harness application writes them when you configure the rule from the visual editor. `retry` only works in the object form shown in [Retry](#retry); there is no bare-string shorthand for it.

Harness validates the action when the pipeline run starts, not when you save the pipeline. The schema currently accepts any action under `environment.on-failure`, so a disallowed action only surfaces at run time, with the error `Invalid failure strategy action provided for environment`.

***

## Precedence

Harness checks the environment rule first. If the error that occurred does not match any `errors` entry in the environment rule, Harness falls back to the stage `on-failure` rule.

For example, if the environment rule only lists `errors: [approval-rejection]` and the actual failure is an infrastructure-not-found error, the environment rule does not match, and the stage rule applies instead.

If the stage rule specifies an action that is not allowed on an environment, such as `ignore`, Harness still applies that inherited action to the Infrastructure node rather than skipping it.

***

## Retry

Configure the number of attempts, the interval between them, and the action to take once attempts are exhausted:

```yaml
environment:
  items:
    - id: production
      deploy-to: production-cluster
  on-failure:
    - errors: [all]
      action:
        retry:
          attempts: 3
          interval: 30s
          failure-action: fail
```

A retry's `failure-action` cannot be `retry` or `ignore`. Harness rejects both, which is stricter than NG, where an invalid `failure-action` after retry quietly falls back to marking the stage as failed.

***

## Multiple environments

When `items` lists more than one environment, the `on-failure` rule applies to the whole list. You cannot set a different rule per environment. Each environment in the list resolves on its own, so one environment failing does not stop or affect the others.

Add a `multi-deployment` block next to `service` and `environment` at the stage level to control whether Harness keeps resolving the remaining environments after one fails, and to cap how many run at the same time. This corresponds to `maxConcurrency` and `shouldProceedIfFailed` on an NG matrix strategy:

```yaml
stages:
  - name: deploy
    id: deploy
    environment:
      items:
        - id: us-east
          deploy-to: us-east-cluster
        - id: us-west
          deploy-to: us-west-cluster
        - id: eu-central
          deploy-to: eu-central-cluster
      on-failure:
        - errors: [all]
          action: stage-rollback
    multi-deployment:
      on-failure: run-all
      max-concurrency: 2
```

`run-all` keeps resolving the remaining environments after a failure. `skip-queued` stops starting new ones once a failure occurs, but lets any already-running environment finish. `max-concurrency` only caps how many environments run at once; it never increases concurrency on its own. To run environments side by side, add `parallel: true` under `environment`:

```yaml
stages:
  - name: deploy
    id: deploy
    environment:
      parallel: true
      items:
        - id: us-east
          deploy-to: us-east-cluster
        - id: us-west
          deploy-to: us-west-cluster
    multi-deployment:
      on-failure: run-all
      max-concurrency: 2
```

`multi-deployment.on-failure` and `max-concurrency` can also be set as runtime inputs, so you can choose the behavior when you run the pipeline:

```yaml
multi-deployment:
  on-failure: <+input>.allowedValues(run-all,skip-queued)
  max-concurrency: <+input>
```

***

## Important notes

* Harness has only run-tested the `unknown` error type at the environment scope. Most other error types in the `errors` list map through the same validation as step-level strategies, but cannot actually occur while resolving an environment.
* A valid environment pointing at an infrastructure that does not exist is handled by the environment rule on the Infrastructure node, matching NG behavior.
* If a failure occurs inside the rollback's own infrastructure step, that error also lands on the rollback's Infrastructure node, and the environment rule applies to it.
* With `all-infra: true`, the environment rule still applies on the Infrastructure node the same way it does for a single named infrastructure.
* An `on-failure` rule without an `action` is rejected when the run starts.

***

## Next steps

* Go to [Service failure strategy](https://developer.harness.io/continuous-delivery/3.0/deployment-entities/service/failure-strategy.md) to configure the same behavior for service resolution.
* Go to [On failure](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/overview/strategy/on-failure) to review the stage-level failure strategy that the environment rule falls back to.

{% @harness-feedback/feedback %}
