> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix a job that stays queued, a lane that fell back, and a job that fails on a Darkbloom runner.

## A job stays queued

Check whether its lane was routed to Darkbloom. A lane that was routed cannot
fall back any more: if Darkbloom then refuses its jobs (a balance too low to
hold, a revoked link or consent, a cap reached meanwhile, or repeated
infrastructure failures), they stay queued on GitHub. Cancel the run and re-run
it, which routes again. With the watchdog workflow that happens by itself after
the configured wait.

A job can also wait queued because it is at your concurrency or resource limit.
The watchdog cannot tell that wait from a fault: raise
`DARKBLOOM_WATCHDOG_MINUTES` above it.

## A lane fell back

The route job's summary gives the reason. The reasons and what to do:

| Reason | What to do |
| - | - |
| `routing is off`, `pull request from a fork` | Nothing: expected |
| `plane request failed (HTTP …)` | Darkbloom did not answer in time; it retries once |
| `plane: repository_not_approved` | Request access, or renew an expired approval |
| `plane: lane_not_enabled`, `profile_not_approved` | The approval does not cover this lane or profile yet |
| `plane: event_not_admitted`, `branch_not_admitted` | The approval does not cover this event or branch |
| `plane: payer_not_authorized` | Link the installation |
| `plane: monthly_spend_cap` | Raise the cap, or wait for the next month (UTC) |
| `plane: no_capacity`, `reservation_cap` | Darkbloom is full right now |
| `plane: profile_degraded` | Recent Darkbloom jobs of this repository failed; it retries after a cool-down |
| `plane: paused`, `routing_disabled`, `billing_unavailable`, `intake_degraded`, `unavailable`, `image_not_available` | A Darkbloom-side pause or problem; nothing to do |
| `plane: run_fallback_forced` | An earlier attempt of this run waited too long for a Darkbloom runner, so the run was cancelled and re-run on its fallback runners (by Darkbloom's watchdog or yours); nothing to do |

The route workflow itself can also keep every lane on its fallback:

| Decision | What to do |
| - | - |
| `not requested` | The lane's count is 0 |
| `plane URL is not https` | Set `DARKBLOOM_SANDBOX_URL` to an `https://` URL |
| `run identity is unavailable` | Check that the run ID and attempt are numeric |
| `plane reply is malformed` | Darkbloom's answer was not one route; nothing to do |
| `plane decision is missing or invalid` | The answer did not repeat the requested labels; nothing to do |

## A job fails on a Darkbloom runner

* **It uses a secret, an environment, services, a container or a container
  action.** Those jobs are refused and stay queued. Move secrets to environments
  and keep such jobs on your own runners.
* **Its permissions are missing or `read-all`.** A routed job needs explicit
  `read` or `none` permissions on the job or the workflow.
* **It calls a reusable workflow from another repository.** Darkbloom cannot
  verify it, so every routed job of that workflow is refused. Copy the route
  workflow locally and keep the job's workflow free of remote reusable
  workflows.
* **It downloads from an unapproved host.** The step fails. Ask your Darkbloom
  contact to add the host; see [caching and network](https://docs.darkbloom.dev/ci/caching-and-network.md).
* **A tool is missing or a version differs.** Check
  [runner images](https://docs.darkbloom.dev/ci/runner-images.md). Linux jobs cannot `apt install`; install
  into the scratch disk or use an action.
* **A cache misses.** A job on another Mac misses Darkbloom's build cache, and
  pull requests from forks get none. GitHub's caches behave as usual.
* **The Mac dropped off the network.** GitHub fails the job. If Darkbloom
  operates your approval's watchdog for that lane, it re-runs the job once,
  after the run completes.
* **It publishes, releases or deploys.** Keep those jobs on your own runners,
  and keep the jobs that save caches releases restore there too.

## Pull requests from forks

The route workflow keeps them on their fallback runners without asking
Darkbloom. Nothing is wrong.

## Darkbloom is down

Lanes fall back before any job is queued, so new runs use your runners. Jobs
already routed wait for Darkbloom; if it refuses them they stay queued, and you
cancel and re-run. The watchdog workflow does that after its wait.

## The approval expired

Lanes fall back until it is renewed: choose **Request renewal** in the console.
A denied request says the operator's reason; fix it and choose **Request
again**.

## Stop using Darkbloom

Set the repository variable `DARKBLOOM_ROUTING` to anything but `on`, or remove
the route job. **Disconnect** the installation in the console to stop paying
for it, and uninstall the App on GitHub to remove its access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.