# Troubleshooting CI

What to do when a run does not start, waits, or fails before its jobs.

## A push starts no run

**Cause:** The workflow file does not parse, its triggers do not match the push, or it is not in a
workflow folder. A file that does not parse is not reported on the push.

**Fix:** Check the file (see [Add a workflow](add-a-workflow.md)) and its `on:` section. A `push`
trigger with only `branches:` never fires for a tag, and one with only `tags:` never for a branch.

## The run fails with `Secret "NPM_TOKEN" is not granted to CI for this repository`

**Cause:** The secret exists but has no `actions` grant covering this repository, or the grant
expired.

**Fix:** Grant it (the failed run offers **Grant _NPM_TOKEN_ to CI**), then re-run. A secret that
does not exist fails with `Secret "NPM_TOKEN" does not exist in this organization. …`; check the
name under **Secrets**. See [Give a job a secret](give-a-job-a-secret.md).

## The run waits with "Waiting for a free slot"

**Cause:** Your organization has as many runs on platform machines as its ceiling allows.

**Fix:** Wait, or cancel a run; **See what is running** on the run lists them.

## The run waits with "none is online"

**Cause:** No runner with the label the job needs is online: none is registered, or the machine is
off, asleep, or its runner stopped.

**Fix:** Start the runner, wake the Mac (and set it never to sleep), or register one (see
[Register a runner](register-a-runner.md)). On a Mac, `sudo launchctl kickstart -k system/app.deutschecloud.ews-runner`
restarts the agent. A run still waiting after 20 minutes with no runner of the label online fails
with `no online runner with label macos`; re-run it once a runner is online. A run whose runners
are online but busy waits longer (see the next section).

## The run waits with "is busy with another run"

**Cause:** Every runner with the label is executing another run.

**Fix:** Wait, cancel the earlier run, or register another runner with the label.

## A native run with a `linux` and a `macos` job never starts

**Cause:** One runner must take the whole run, and a Mac cannot carry the `linux` label.

**Fix:** Put the macOS jobs in a workflow file of their own.

## A step fails with `Step kind "build-image" needs a container engine`

**Cause:** An image step in a `macos` job; the Mac has no container engine.

**Fix:** Move the step to a `linux` job in another workflow file.

## A GitHub-syntax job shows "macOS jobs can't share a run with jobs on Deutsche Cloud's one-machine-per-run Linux hosts"

**Cause:** The run also has Linux jobs on the hosted machines.

**Fix:** Create a runner pool that carries the Linux labels (see
[Create a runner pool](create-a-runner-pool.md)), or move the macOS jobs to their own workflow file.

## A job shows "not run: its if: condition was false, or a job it needs did not succeed"

**Cause:** Its `if:` was false, or a job in its `needs` did not succeed.

**Fix:** Look at the job it needs.

## A scheduled workflow never runs

**Cause:** Schedules are read from the default branch when it is pushed.

**Fix:** Push to the default branch after adding the schedule.

## A runner shows **Offline** although the machine is on

**Cause:** It has not reported for five minutes; it cannot reach the console.

**Fix:** On a Mac, read `/usr/local/ews-runner/logs/runner.err.log`. Check outbound HTTPS to the
console.

## A build on a Mac cannot find a tool that works in Terminal

**Cause:** Steps run as root; the tool is installed for another user.

**Fix:** Install it for every user, or set `PATH` in the job's `env:`.

## Related

- [Watch a run](watch-a-run.md)
- [Runners and runner groups](runners-and-groups.md)
