> 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/service/failure-strategy.md).

# Failure strategy

Configure what Harness does when a service fails to resolve. The service rule is checked first; if it doesn't match the error, the stage failure strategy applies.

A service-level `on-failure` rule controls what Harness does when a failure occurs while resolving a service. The service rule is checked first; if it doesn't match the error, the stage failure strategy applies. Before this rule existed, a failure while resolving the service fell through to the stage `on-failure` rule, the same as any other failure, with no way to react to it differently.

***

## YAML

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

```yaml
service:
  items:
    - checkout-service
  on-failure:
    - errors: [all]
      action: abort
```

A service rule only reacts to a failure while Harness resolves the service itself. 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 a service, and which are rejected
* How the service rule and the stage rule interact
* How to configure retry on a service
* How `on-failure` behaves when you deploy a list of services

***

## Actions

| YAML value             | Allowed on a service | 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 service resolution up to a configured number of attempts.                                         |
| `stage-rollback`       | No                   | Rejected. Nothing has deployed yet when service resolution fails, so there are no rollback steps to run. |
| `ignore`               | No                   | Rejected.                                                                                                |
| `success`              | No                   | Rejected.                                                                                                |
| `proceed-with-default` | No                   | Rejected.                                                                                                |
| `manual-intervention`  | No                   | Rejected.                                                                                                |
| `retry-step-group`     | No                   | Rejected.                                                                                                |

On a service, `abort`, `fail`, and `pipeline-rollback` can be written as a bare string, the same way the visual editor writes them. `retry` only works in the object form shown in [Retry](#retry).

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

***

## Precedence

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

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

If the stage rule specifies an action that is not allowed on a service, such as `ignore`, Harness still applies that inherited action to the service 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
service:
  items:
    - checkout-service
  on-failure:
    - errors: [all]
      action:
        retry:
          attempts: 3
          interval: 30s
          failure-action: fail
```

A retry's `failure-action` must be `abort`, `fail`, or `pipeline-rollback`. Any other action is rejected when the run starts.

***

## Multiple services

When `items` lists more than one service, the `on-failure` rule applies to the whole list. You cannot set a different rule per service. Each service in the list resolves on its own, so one service 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 services 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
    service:
      items:
        - checkout-service
        - payments-service
        - cart-service
      on-failure:
        - errors: [all]
          action: abort
    multi-deployment:
      on-failure: run-all
      max-concurrency: 2
    environment:
      items:
        - id: production
          deploy-to: production-cluster
```

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

```yaml
stages:
  - name: deploy
    id: deploy
    service:
      parallel: true
      items:
        - checkout-service
        - payments-service
    multi-deployment:
      on-failure: run-all
      max-concurrency: 2
    environment:
      items:
        - id: production
          deploy-to: production-cluster
```

`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

* A Kubernetes "service not found" error at stage Initialize is handled by the service rule, the same as any other service-resolution failure. Other Initialize errors still fail the stage immediately.
* An `on-failure` rule without an `action` is rejected when the run starts.

***

## Next steps

* Go to [Environment failure strategy](https://developer.harness.io/continuous-delivery/3.0/deployment-entities/environment/failure-strategy.md) to configure the same behavior for environment and infrastructure 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 service rule falls back to.

{% @harness-feedback/feedback %}
