Deployments & Runs

Resolve environment not found errors, slug conflicts, stuck runs, approval blocks, and lock issues during deployments

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
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

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

CLI

Common causes and fixes

• Runner pod OOMKilled: increase runner memory limits. See Self-Hosted Runner Troubleshooting

• 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

---

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

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

CLI

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.

---

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

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)

CLI

If you are consistently hitting cost limits, review the infrastructure scale in your blueprint before increasing the quota.

---

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

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.

---

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

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

CLI

For a deeper explanation of state and drift, see State Management.

---

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

CLI

List all environments to check whether the slug exists:

bricks deploy list

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

Bluebricks app

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.

For background on environment lifecycle, see Environments in the main documentation.

---

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

This is different from 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.

---

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

CLI

List existing environments to find the conflicting slug:

bricks deploy list

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

Bluebricks app

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 for status definitions

4. Contact support with the environment name and run ID