# Deployments & Runs

## Quick reference

| Symptom                                 | Cause                                       | Fix                                          |
| --------------------------------------- | ------------------------------------------- | -------------------------------------------- |
| Run stuck in "Planning" or "Installing" | Runner resource constraints or connectivity | Check runner logs and cluster connectivity   |
| **Approve & Apply** button disabled     | You are not the collection owner            | Contact the collection owner for approval    |
| Cost quota exceeded                     | Projected cost exceeds the collection limit | Owner increases quota in **Policies**        |
| Failed to acquire lock                  | Another run is in progress                  | Wait for the current run to complete         |
| Plan shows unexpected changes           | Infrastructure drift from manual changes    | Run drift detection to identify actual state |

***

## Run stuck in planning or installing

A run can appear stuck when the self-hosted runner cannot complete the IaC operation. This is usually a resource or connectivity issue.

### How to diagnose

{% tabs %}
{% tab title="Bluebricks app" %}

1. Open the **Environments** page
2. Click the stuck environment to view run details
3. Check the **Logs** tab for error messages or timeouts
   {% endtab %}

{% tab title="CLI" %}
List recent deployments to find the stuck run:

```bash
bricks deploy list
```

For self-hosted runner logs, check the Kubernetes cluster:

```bash
kubectl logs -f deployment/bdc-bluebricks-deployments-controller -n <namespace>
```

{% endtab %}
{% endtabs %}

### Common causes and fixes

* **Runner pod OOMKilled**: increase runner memory limits. See [Self-Hosted Runner Troubleshooting](https://bluebricks.co/docs/help/troubleshooting/self-hosted-runner)
* **Network timeout**: verify the runner can reach your cloud provider and the Bluebricks API
* **Missing cloud credentials**: confirm the collection has a valid [cloud account connected](https://docs.bluebricks.co/bluebricks-documentation/collection/what-is-a-cloud-account)

***

## Approve & Apply button disabled

Only collection owners can approve and apply runs when the Owner Approval policy is enabled.

### How to fix

{% tabs %}
{% tab title="Bluebricks app" %}

1. Open the environment's run details
2. If the **Approve & Apply** button is grayed out, you do not have owner permissions
3. Ask a collection owner to approve the run, or request owner access from the collection's **Overview** tab under **Assigned Users**
   {% endtab %}

{% tab title="CLI" %}
Approval is currently available through the Bluebricks app only. Contact your collection owner to approve the pending run.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The Owner Approval policy can be configured per collection. For details, see [Policies](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/collections/policies).
{% endhint %}

***

## Cost quota exceeded

The Cost Limit policy prevents runs that exceed a configured cost threshold for the collection.

### How to fix

{% tabs %}
{% tab title="Bluebricks app" %}

1. Go to the collection's **Policies** tab
2. Find the **Cost Limit** policy
3. The collection owner can either:
   * Increase the cost limit
   * Approve the run despite the quota violation (owner override)
     {% endtab %}

{% tab title="CLI" %}
Cost quota management is available through the Bluebricks app. Check the collection's policies and contact the owner to adjust the limit.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
If you are consistently hitting cost limits, review the infrastructure scale in your blueprint before increasing the quota.
{% endhint %}

***

## Failed to acquire lock

State locks prevent concurrent modifications to the same infrastructure. If a previous run failed or is still in progress, the lock may still be held.

### How to fix

1. **Wait**: if another run is in progress, let it complete
2. **Check status**: open the environment in the Bluebricks app or run `bricks deploy list` to see if a run is active
3. **Stale lock**: if no run is active but the lock persists, contact your organization admin to release the lock

{% hint style="danger" %}
Manually releasing a state lock can cause state corruption if a run is still in progress. Only release locks when you are certain no active run holds them.
{% endhint %}

***

## Plan shows unexpected changes

If a plan includes changes you did not make, infrastructure drift is likely. Drift happens when resources are modified outside of Bluebricks (for example, through the cloud provider console or a separate IaC tool).

### How to fix

{% tabs %}
{% tab title="Bluebricks app" %}

1. Open the environment and review the plan diff
2. Identify resources that were manually changed
3. Either:
   * **Accept the drift**: approve the plan to bring the state back in sync
   * **Revert manual changes**: fix the resources in the cloud provider, then re-plan
     {% endtab %}

{% tab title="CLI" %}
List deployments and review the latest plan:

```bash
bricks deploy list
```

Check the plan output in the Bluebricks app for a detailed diff of what changed.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
For a deeper explanation of state and drift, see [State Management](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/runs/state-management-and-history).
{% endhint %}

***

## Still stuck?

1. Enable logging: `bricks logger enable`
2. Check runner logs if using a self-hosted runner
3. Review [Monitoring Runs](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/runs/monitoring-runs) for status definitions
4. [Contact support](https://www.bluebricks.co/support) with the environment name and run ID