# Fix a board that doesn't build or ship

Source: https://opvs.ai/docs/factory/fix-a-build

> What to do when cards are not claimed, a build fails, or a pull request does not merge.

Use this page when your machine and desk are `ready` but cards are not built, a build fails, or a pull request does not ship. Work down the checks in order: the first one that fails is your answer.

## Nothing is claimed

Check these five things, in this order:

```bash
opvs boards projects <board-id>                      # 1. resolution must be "resolved"
opvs tasks list --board <board-id> --status pending  # 2. are the cards in Ready, or still in Backlog?
opvs boards health <board-id> --profile factory      # 3-4. roles and claim wiring
opvs tasks get <REF>                                 # 5. ready_for_builders
```

Check

When it fails

What to do

1. One project

`none`: the board is in no active project. `ambiguous`: it is in two

`opvs projects add-board <project-id> <board-id>`, or `opvs boards move-to-project <board-id> <project-id> --yes` to leave the other one

2. Ready, not Backlog

New cards land in Backlog, which builders never claim

`opvs tasks move <REF> --column "Ready"`

3. The builder's role

Ready is claimable by the role `builder`. A builder with any other role gets `no_claimable_columns_for_role`

Give the worker the role `builder`, or no role

4. A column declares a role

A board that was only retyped to `factory` has no claim rules

Create the board as `factory` with a preset, or set `--claimable-by-roles builder` on Ready

5. The builder switch

Board **Settings → Builders** is off

Switch it on. Every card that is truly ready is claimed at the next poll

A dependency can also hold a card back. A card is not claimable until every card it waits on is done, and a card that waits on something that can never finish waits forever without an error. The `dead_dependency` check in `opvs boards health` finds those.

## The card is in Ready but not ready for builders

`opvs tasks get <REF>` lists what is missing under `ready_for_builders.missing`. A builder needs a brief of at least 200 characters, a harness, the credential that harness needs, and a task type.

**Fix:** fill what `missing` names. If the card should stay with a person, set `opvs tasks update <REF> --claimable-by human`.

## A build failed

Read the card first:

```bash
opvs tasks get <REF>     # blocked_reason, and the gate output in the comments
opvs builds read <REF>   # while it runs: the current command and recent steps
```

A **first** build that fails pushes nothing. A build sent back onto its own open pull request is different: a red test run can still push commits, and the pull request is labelled `hold:red` until a green push removes the label.

**To run a failed card again,** clear its blocked reason, then move it to Ready in **one** write. Two writes let a builder claim between them, and the card runs twice. Never move a Done card back to Ready: it is claimed and rebuilt within seconds.

## A desk claims a card and fails within seconds

The desk is switched on but cannot run the card's engine. Read `worker.harnesses` in the desk's health: it lists which engines it can run and why the others are not available. Pin the card to an engine the desk has, or install that engine on the desk.

## The pull request opened but the card is still Executing

Read the card's `status`, not only its column. If it did not move to `review`, move it yourself and note why in a comment.

## The pull request is a draft

Changes in the risky set (migrations, auth, billing, security, money) open as draft pull requests. A builder never marks them ready. A person reviews and marks them ready in the same step as signing off. Your [review policy](/developers/factory/review-policy) decides what counts as risky for your repository.

## Nothing merges

```bash
opvs ship status --project <project-id>
```

What status shows

Why

What to do

No ship line (`ship_line_not_found`)

The project has none yet

`opvs ship set --project <project-id> --enabled off --mode practice --after-merge merge-only`

`mode: practice`

Practice watches and does not ship

`opvs ship set --project <project-id> --mode live`

Ship app `not connected`, `repository missing`, `installation removed` or `suspended`

GitHub is not connected for this repository

`opvs ship connect --project <project-id>`, then see [Connect GitHub](/developers/factory/connect-github)

The pull request is held

Someone ran `opvs ship hold`

`opvs ship release <pr> --project <project-id>`

An owner-class release waits

It needs approval of its exact head commit from a ship-line owner

`opvs ship approve <pr> --head <40-char-sha> --project <project-id>`

A slug that matches two projects is refused; pass the project's id from `opvs projects list`.

Related: [How a card moves](/developers/factory/card-flow), [Board health](/developers/guides/board-health).
