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

# Troubleshoot setup and connections

> Diagnose common problems while preparing a Project and its integrations.

Use Yellowhammer's visible refusal and diagnostic findings to identify the failed connection, Project, or local tool before changing configuration.

## Start with the diagnostic report

With the [command-line tool installed](https://yellowhammer.dev/docs/reference/yh-command-line.md), run these checks for your Project. `acme-checkout` is an illustrative id:

```bash theme={null}
yh validate
yh doctor --project acme-checkout
```

`validate` is offline. Ordinary `doctor` reports readiness without repairing it. Read the finding's subject and full message; a machine-wide failure can affect several Projects even when the report is filtered to one.

## Configuration or Project is unavailable

Open **Settings → Refused Files**. Read the named file, key, line, and validation error where supplied. Correct the file in `~/.config/yellowhammer/`, then run `yh validate` again. Each Project file must match its permanent Project id, and a Repo cannot belong to two Projects.

If a Repo path is unavailable, verify that the checkout exists at its configured path and is registered in Orca ADE. Inspect **Settings → your Project → Configuration → Repos** and the `orca` and `git` findings before trying another Night.

## Linear connection will not complete

Open **Settings → Boards** and inspect the intended Board Connection and workspace. Confirm that you approved the intended Linear workspace and that the selected Operator identity is yours. For remote approval, wait for the approving administrator's result before treating the connection as ready. Follow [Connect Linear](https://yellowhammer.dev/docs/setup/connect-linear.md) for the supported connection flow.

```bash theme={null}
yh doctor --check linear --project acme-checkout
```

For an authorization failure, reconnect the affected Board Connection in **Boards**. A connection to a different workspace cannot be repaired by changing only a Project's Linear project id; its workspace is fixed for its life.

If diagnostics report missing provisioned board states or labels, choose **Repair** in the Project's Health card or run:

```bash theme={null}
yh doctor --fix --check linear --project acme-checkout
yh doctor --check linear --project acme-checkout
```

Repair creates missing items without renaming or deleting existing ones. A name collision or refused creation remains a failure; follow the action named in that finding rather than repeatedly recreating the connection.

## GitHub access fails

Open **Settings → Code Hosting** and inspect the connection selected by the Project. Check that its account can access and push to every working Repo, then run:

```bash theme={null}
yh doctor --check github --project acme-checkout
```

For a different account or credential, follow [Connect GitHub](https://yellowhammer.dev/docs/setup/connect-github.md). In the Project's **Configuration → Code Hosting**, select the replacement and choose **Change connection**; the engine checks push access before saving the selection. Correct the credential or permission named by a refusal before retrying publication.

## Agent CLI is not ready

Open **Settings → Agent CLIs**. Inspect the executable, latest Probe findings, and routing eligibility. Authenticate the CLI under the macOS account used for the Night, then choose **Probe Now** or **Probe Again**.

A failed unattended-dispatch, result-file, or process-containment finding can exclude a CLI from routing. Read the Probe log for the actual vendor refusal. If it names an unavailable model or effort, choose a combination your account supports and re-probe with explicit options from `yh probe --help`.

If the CLI works in a terminal but is missing overnight, check its declared executable and the tool path captured in the scheduled jobs. Reinstall or regenerate jobs after correcting the installation path. See [Configure the schedule](https://yellowhammer.dev/docs/run/configure-the-schedule.md).

## Gather details for support

Collect the Project id, connection name, exact finding, time, relevant app or CLI version, and logs for the failing operation. Include the failed Probe finding when applicable. Remove tokens, credential values, and private source content before sharing.

## Next steps

[Troubleshoot Nights and missing results](https://yellowhammer.dev/docs/reference/troubleshoot-nights-and-missing-results.md) · [Settings](https://yellowhammer.dev/docs/reference/settings.md)


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