> 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/harness-platform/3.0/harness-platform-resources/pipelines/barriers.md).

# Barriers

In complex pipelines that orchestrate interdependent services or components, you may need to coordinate the execution flow across different stages or step groups. For example, you might want to verify a group of services only after all of them are deployed successfully.

Harness provides **Barriers** to help with this kind of synchronization. A barrier pauses execution at defined points so that multiple parallel entities, such as stages or step groups, proceed only after all required parts reach the same barrier.

{% hint style="info" %}
Barrier steps are only supported inside **Deploy** and **Custom** stage types.
{% endhint %}

### What you will learn from this topic <a href="#what-you-will-learn-from-this-topic" id="what-you-will-learn-from-this-topic"></a>

* How [barriers work](#how-barriers-work) to synchronize parallel execution
* How [barrier scope](#barrier-scope) determines where barriers can be used
* How [barrier synchronization requirements](#barrier-synchronization-requirements) prevent deadlocks
* How [barrier failure behavior](#barrier-failure-behavior) affects pipeline execution
* How to use [barriers and looping strategies](#barriers-and-looping-strategies) together
* How to [add a barrier](#add-a-barrier) to your pipeline
* How to [use a barrier in a step](#use-a-barrier-in-a-step) within stages
* How to [use multiple barriers in a stage or step group](#use-multiple-barriers-in-a-stage-or-step-group) for different synchronization points
* How to [avoid rollback barrier cycles](#avoid-rollback-barrier-cycles) that cause deadlocks
* [When to use barriers](#when-to-use-barriers) versus other flow-control options

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **Harness project access**: You need View and Edit permissions on [Pipelines](/harness-platform/3.0/harness-platform-resources/platform-access-control/permissions-reference.md#pipelines). An administrator must assign you a role that includes these permissions. For more information, refer to [RBAC in Harness](/harness-platform/3.0/harness-platform-resources/platform-access-control/rbac-in-harness.md).
* **Existing pipeline**: You need a pipeline with parallel stages or step groups to use barriers. For more information, refer to [Add a stage](/harness-platform/3.0/harness-platform-resources/pipelines/add-a-stage.md).

***

### How barriers work <a href="#how-barriers-work" id="how-barriers-work"></a>

Barriers follow these rules:

* A barrier synchronizes two or more stages or step groups that use the same **Barrier Reference** and can execute concurrently.
* All participating stages or step groups must reach the barrier before any of them can proceed.
* If a participating stage or step group fails before reaching the barrier, the other participants are signaled to fail.
* If a participant does not reach the barrier before the timeout, the barrier fails.
* Each affected stage or step group follows its configured failure strategy.

{% hint style="info" %}
Barriers are scoped to a single pipeline by default. Barriers can also synchronize stages across parent and child pipelines when the `PIPE_BARRIERS_FOR_CHAINED_PIPELINES` feature flag is enabled. Contact [Harness Support](mailto:support@harness.io) to enable the feature.
{% endhint %}

#### Barrier scope <a href="#barrier-scope" id="barrier-scope"></a>

Barriers are scoped to a pipeline. The same barrier reference can be used by multiple stages or step groups within the same pipeline to synchronize execution. A barrier reference cannot normally be used across separate pipelines. For example, a barrier created in one pipeline cannot be referenced by a stage in another pipeline.

Barriers can also be used across parent and child pipelines when the feature for chained pipelines is enabled. For more information, refer to [Pipeline chaining in Harness](/harness-platform/3.0/harness-platform-resources/pipelines/pipeline-chaining.md).

This is especially useful because your pipelines can coordinate execution flows both within a single pipeline and across pipeline hierarchies.

#### Barrier synchronization requirements <a href="#barrier-synchronization-requirements" id="barrier-synchronization-requirements"></a>

A barrier only synchronizes execution when the related stages or step groups can reach the barrier concurrently.

Do not use the same Barrier Reference in sequential stages or step groups. The first stage or step group waits at the barrier for a later one, but the later one cannot start until the first stage completes, resulting in a deadlock.

#### Barrier failure behavior <a href="#barrier-failure-behavior" id="barrier-failure-behavior"></a>

If a stage or step group fails before reaching a shared barrier, the other stages or step groups waiting at the barrier are also signaled to fail. Each affected stage or step group follows its configured failure strategy.

If a stage or step group does not reach the barrier before the barrier timeout expires, the barrier is considered failed and execution fails according to the configured failure strategy.

***

### When to use barriers <a href="#when-to-use-barriers" id="when-to-use-barriers"></a>

Use barriers when you need to synchronize execution at parallel stages or step groups at a specific point in a pipeline.

For example, if multiple services are deployed in parallel and a verification step should run only after all deployments reach a specific point, use a barrier to synchronize them.

Use other flow-control options for different requirements:

* **Barriers**: Synchronize parallel stages or step groups within a pipeline.
* **Resource Constraints**: Prevent simultaneous deployments to the same service or infrastructure combination.
* **Queue steps**: Control the execution order of pipeline executions that share a resource key.

***

### Barrier synchronization example <a href="#barrier-synchronization-example" id="barrier-synchronization-example"></a>

Here is a visualization of how barriers synchronize parallel stages:

* **Stage A** and **Stage B** both wait at **Barrier X** and proceed only when both reach it.
* **Stage B** and **Stage C** both wait at **Barrier Y** and proceed together once both are ready.

This allows you to control complex coordination logic within a pipeline without resorting to manual delays or checks.

***

### Add a barrier <a href="#add-a-barrier" id="add-a-barrier"></a>

A barrier is a name added in a pipeline's **Flow Control** settings.

Perform the following steps to add a barrier:

1. In your pipeline, select **Flow Control**.
2. In **Flow Control**, select **Add Barrier**.
3. In **Barrier Name**, enter a unique name, and then click outside of the settings. The barrier is created.

Next, select the name using the **Barrier** step in the stages where you want to synchronize.

***

### Use a barrier in a step <a href="#use-a-barrier-in-a-step" id="use-a-barrier-in-a-step"></a>

Perform the following steps to apply a barrier:

1. In your stage, under **Execution**, select **Add Step**, and then select **Barrier**.
2. Enter a name for the step.
3. In **Timeout**, enter the timeout period in milliseconds. For example, `600000` milliseconds is 10 minutes. The timeout period determines how long each stage with a barrier must wait for the other stages to reach the barrier point. When the timeout expires, it is considered a deployment failure.
4. Barrier timeouts are not hard timeouts. A barrier can fail anytime between the timeout value and `timeout + 1 minute`.
5. In **Barrier Reference**, select the name of an existing barrier.
6. Select **Apply Changes**.

***

#### Use multiple barriers in a stage or step group <a href="#use-multiple-barriers-in-a-stage-or-step-group" id="use-multiple-barriers-in-a-stage-or-step-group"></a>

You can add multiple Barrier steps to the same stage or step group. Each Barrier step in the same stage or step group must use a different **Barrier Reference**.

For example, a stage can use one barrier to synchronize deployment steps and another barrier to synchronize verification steps later in the same stage.

Use the same Barrier Reference across different parallel stages or step groups that should synchronize at a particular point.

***

### Barriers and looping strategies <a href="#barriers-and-looping-strategies" id="barriers-and-looping-strategies"></a>

Barriers can also be used with looping strategies. Additional constraints apply when you use barriers in looped parallel executions. For more information, refer to [Using barriers with looping strategies](/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/flow-control/synchronize-deployments-using-barriers.md#using-barriers-with-looping-strategies).

#### Important considerations for looping strategies <a href="#important-considerations-for-looping-strategies" id="important-considerations-for-looping-strategies"></a>

When using barriers with looping strategies:

* Use the same **Barrier Reference** for all looped stages or step groups that need to synchronize.
* Do not use **`maxConcurrency`** in a looping strategy that contains a barrier. Some iterations might not start until earlier iterations finish, while running iterations wait at the barrier, causing the pipeline to become stuck.
* For multi-service deployments, enable **Deploy Services in Parallel** so all participating stages can reach the barrier.
* A barrier can synchronize multiple groups of looped stages or a single stage group with looped stages, as long as the participating executions use the same Barrier Reference.

***

### Avoid rollback barrier cycles <a href="#avoid-rollback-barrier-cycles" id="avoid-rollback-barrier-cycles"></a>

Do not reuse the same **Barrier Reference** in both the normal execution flow and a rollback section. A barrier waits for every position that shares its reference, including any position in a rollback section. Because rollback steps run only when the normal flow fails, that rollback position never arrives during a successful run, so the barrier keeps standing and the pipeline hangs until the step timeout.

For example, if the reference `wall3` is used in the normal steps of two parallel stages and also in the rollback steps of one stage, the two normal-flow positions reach the barrier and wait for the rollback position. The rollback position does not execute unless the stage fails, so the pipeline stalls and eventually times out.

To synchronize a rollback flow, use a dedicated barrier reference for rollback instead of the one used in the normal flow.

<details>

<summary>Barrier reference cycle (anti-pattern) and the corrected configuration</summary>

```yaml
# Anti-pattern: barrier "wall3" is referenced in both normal and rollback steps <a href="#anti-pattern-barrier-wall3-is-referenced-in-both-normal-and-rollback-steps" id="anti-pattern-barrier-wall3-is-referenced-in-both-normal-and-rollback-steps"></a>
pipeline:
  stages:
    - parallel:
        - stage:
            name: deploy
            spec:
              execution:
                steps:
                  - step:
                      type: Barrier
                      spec:
                        barrierRef: wall3        # normal flow
                rollbackSteps:
                  - step:
                      type: Barrier
                      spec:
                        barrierRef: wall3        # rollback flow -> cycle
        - stage:
            name: deploy2
            spec:
              execution:
                steps:
                  - step:
                      type: Barrier
                      spec:
                        barrierRef: wall3        # normal flow
  flowControl:
    barriers:
      - identifier: wall3
```

```yaml
# Corrected: use a dedicated reference for the rollback flow <a href="#corrected-use-a-dedicated-reference-for-the-rollback-flow" id="corrected-use-a-dedicated-reference-for-the-rollback-flow"></a>
  flowControl:
    barriers:
      - identifier: wall3            # normal flow
      - identifier: wall3_rollback   # rollback flow
# Set barrierRef: wall3_rollback in the rollback step so it no longer shares "wall3". <a href="#set-barrierref-wall3rollback-in-the-rollback-step-so-it-no-longer-shares-wall3" id="set-barrierref-wall3rollback-in-the-rollback-step-so-it-no-longer-shares-wall3"></a>
```

</details>

Harness detects this anti-pattern and fails validation with a `Barrier Deadlock Detected` error that names the barrier reference and whether it was found in the normal flow, the rollback flow, or both. The check runs both when you save the pipeline and when it starts running, so a barrier reference supplied as a runtime input is caught at execution time. To resolve the error, give the rollback barrier a different reference.

```
Barrier Deadlock Detected: 'wall3' (mixed in normal flow and rollback flow)

Problem:
Barriers with the same reference must execute concurrently (at the same time).
Your pipeline has barriers with 'wall3' that execute sequentially,
creating a deadlock where each barrier waits for the others that have not started yet.
```

The same validation applies to any barriers that share a reference but cannot execute concurrently, such as the same reference reused across sequential stages. Barriers that share a reference and run in parallel remain valid.

{% hint style="info" %}
This validation is behind the feature flag `PIPE_DETECT_BARRIER_CYCLES`. Contact [Harness Support](mailto:support@harness.io) to enable the feature.
{% endhint %}

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* [DAG pipelines](/harness-ai/use-harness-platform/pipelines/dag-pipelines.md): Create pipelines with directed acyclic graph dependencies for complex orchestration.
* [Pipeline chaining in Harness](/harness-platform/3.0/harness-platform-resources/pipelines/pipeline-chaining.md): Chain pipelines together and use barriers across parent and child pipelines.
* [Synchronize deployments using barriers](/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/flow-control/synchronize-deployments-using-barriers.md): Advanced deployment synchronization patterns.