# 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 a collection owner or org admin                   | Contact a collection owner or org admin for approval                                  |
| Cost quota exceeded                     | Total collection cost exceeds the limit                       | Owner or admin 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                                          |
| Environment or deployment not found     | Misspelled slug, wrong collection, or archived                | Verify the slug and collection; [details below](#environment-or-deployment-not-found) |
| Run already in progress                 | Another run is active on this environment                     | Wait for the current run to complete                                                  |
| Environment slug conflicts              | Slug used in another collection or with a different blueprint | Use a unique slug or target the correct collection                                    |
| Conflicting deploy parameters           | Deprecated flags mixed with `deployType`                      | Use only the `deployType` parameter                                                   |

***

## 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 -l app.kubernetes.io/name=bluebricks-deployments-controller -n <namespace>
```

{% endtab %}
{% endtabs %}

### Common causes and fixes

* **Runner pod OOMKilled**: increase runner memory limits. See [Self-Hosted Runner Troubleshooting](/docs/help/troubleshooting/self-hosted-runner.md)
* **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/getting-started/connect-your-cloud)

***

## Approve & Apply button disabled

The **Approve & Apply** button is disabled when you do not have the required permissions. Collection owners, organization admins, and service accounts can approve runs when the Owner Approval policy is enabled.

The button can also be disabled when a cost quota violation is detected, even if you have approval permissions.

### How to fix

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

1. Open the environment's run details
2. If the **Approve & Apply** button is grayed out, check whether it is a permission or cost quota issue:
   * **Permission**: ask a collection owner or org admin to approve the run, or request owner access from the collection's **Overview** tab under **Assigned Users**
   * **Cost quota**: the total collection cost would exceed the limit. A collection owner or org admin can increase the quota in the **Policies** tab or approve with an override
     {% endtab %}

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

{% hint style="info" %}
Organization admins bypass all collection policies, including Owner Approval and Cost Limit. The Owner Approval policy can be configured per collection. For details, see [Policies](https://docs.bluebricks.co/bluebricks-documentation/orchestration/collections/policies).
{% endhint %}

***

## Cost quota exceeded

The Cost Limit policy prevents runs when the total projected cost of all environments in the collection would exceed the configured limit. A deployment can fail this check even if it is individually inexpensive, if the collection's total cost is already near the threshold.

### How to fix

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

1. Go to the collection's **Policies** tab
2. Find the **Cost Limit** policy
3. A collection owner or org admin 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 a collection owner or org admin 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/orchestration/runs/state-management-and-history).
{% endhint %}

***

## Environment or deployment not found

You see `Environment '<slug>' not found` or `Deployment '<slug>' not found` when the identifier you provided does not match any active environment in the target collection. This has several possible causes, and the error message alone cannot tell you which one applies.

### Common causes

* **Misspelled slug**: the slug contains a typo or invalid characters. Environment slugs may contain letters, numbers, hyphens, underscores, and periods. Note: this is different from package names, which only allow letters, numbers, and underscores (no hyphens)
* **Wrong collection**: the environment exists, but in a different collection than the one you targeted
* **Archived environment**: the environment was archived and is no longer visible in standard listings
* **Deleted environment**: the environment was permanently removed

### How to diagnose

{% tabs %}
{% tab title="CLI" %}
List all environments to check whether the slug exists:

```bash
bricks deploy list
```

If the environment does not appear, verify you are targeting the correct collection. Archived environments do not appear in standard listings.
{% endtab %}

{% tab title="Bluebricks app" %}

1. Go to the **Environments** page
2. Search for the environment name or slug
3. If it does not appear, check the **Archived** filter to see if it was archived
4. Verify you are looking in the correct collection using the collection selector
   {% endtab %}
   {% endtabs %}

### If the environment is archived

Archived environments return `Environment '<slug>' is archived`. You must unarchive the environment before deploying to it. In the Bluebricks app, find the environment in the archived list and click **Unarchive**.

{% hint style="info" %}
For background on environment lifecycle, see [Environments](https://docs.bluebricks.co/bluebricks-documentation/orchestration/deployments) in the main documentation.
{% endhint %}

***

## Run already in progress

You see `Environment already has an active run` when you try to trigger a new run while a previous one is still executing. Bluebricks allows only one active run per environment at a time.

### How to fix

1. Check the environment's current run status in the Bluebricks app or with `bricks deploy list`
2. Wait for the active run to complete (or fail) before starting a new one

{% hint style="info" %}
This is different from [Failed to acquire lock](#failed-to-acquire-lock), which is a Terraform state lock held at the infrastructure level. "Run already in progress" is a Bluebricks-level check that prevents concurrent runs on the same environment.
{% endhint %}

***

## Environment slug conflicts

You see an error when deploying to a slug that already exists but does not match what you expect. Three distinct errors fall under this category, and the fix depends on which one you hit.

### Error messages

| Error                                                                     | What it means                                                                                                  |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `Environment slug already exists`                                         | An environment with this slug already exists in the collection                                                 |
| `Collection mismatch: this environment belongs to a different collection` | The slug is in use in a different collection than the one you specified                                        |
| `Package mismatch for deployment`                                         | The slug exists, but the existing environment uses a different blueprint than the one you are trying to deploy |

### How to diagnose

{% tabs %}
{% tab title="CLI" %}
List existing environments to find the conflicting slug:

```bash
bricks deploy list
```

If the slug does not appear, it may exist in another collection. Check the Bluebricks app to search across all collections.
{% endtab %}

{% tab title="Bluebricks app" %}

1. Go to the **Environments** page
2. Search for the slug across all collections
3. Check which collection and blueprint the existing environment uses
   {% endtab %}
   {% endtabs %}

### How to fix

* **Slug already exists, same collection**: if you want to update the existing environment, deploy to it without the draft flag. If you want a separate environment, use a different slug
* **Collection mismatch**: specify the correct collection that owns the existing slug, or use a new slug for the other collection
* **Blueprint mismatch**: you cannot change the blueprint on an existing environment. Create a new environment with a different slug, or destroy the existing one first

***

## Need more help?

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/orchestration/runs/monitoring-runs) for status definitions
4. [Contact support](https://www.bluebricks.co/support) with the environment name and run ID


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/help/troubleshooting/deployments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.