# When something breaks

> What to check first, the commands that show what happened, and how to reach a person.

Source: https://runfoundry.app/docs/operations/troubleshooting/

## Check these first

**Dashboard says No Mac activated yet**

Open Terminal on the Mac and run `foundry status`. If it says the license is not active, run `foundry license activate` with your key.

**A phone shows Offline**

Unlock it, check its cable to the Mac, and run `foundry doctor`. It names what blocks that phone. Then check it against [Phone settings](https://runfoundry.app/docs/setup/phone-settings/).

**A post shows Unknown**

The share was pressed but not confirmed. Check the account in the app. Foundry never sends it again, so nothing double posts.

**Needs you: login, 2FA or checkpoint**

Only you can clear these. Open the app on that phone, finish the step, and the next slot posts.

**Phone says Unable to Verify App, or the runner will not open**

iOS has not checked the Foundry runner with Apple yet, and it needs internet once to do it. Connect the phone to Wi-Fi (or a SIM with working data) and run `/usr/bin/python3 ~/.local/bin/foundry_onboard.py scan` again; the check happens by itself. Still stuck? **Settings › General › VPN & Device Management › Apple Development › Verify App**.

**Timed out while enabling automation mode**

The runner is trusted but iOS will not hand it control. Turn the passcode off (**Settings › Face ID & Passcode › Turn Passcode Off**), then turn on **Settings › Developer › Enable UI Automation**, and run `foundry_onboard.py scan` again.

**TikTok posts show Unknown often**

TikTok's check is the least reliable in this alpha. The post usually went out; look at the profile.

## Install messages

The install line stops at the first problem, prints one line starting `foundry:`. Fix what it names and run the same line again; it picks up where it stopped. Only the last message comes after Foundry is installed, and `foundry license activate <key>` finishes that one.

| What it says | What to do |
| --- | --- |
| `pass your license key` | The key is missing or cut off. Copy it again from your welcome page or **Setup** on your [dashboard](https://runfoundry.app/account); it starts with `fdy1.` and goes after `sh -s --`. |
| `Xcode is not installed` | Install Xcode from the App Store, open it once and accept its license. |
| `Xcode 15 or newer is needed (xcrun devicectl is missing)` | Update Xcode from the App Store, open it once, then run the line again. |
| `/usr/bin/python3 3.9 or newer is needed` | Run `xcode-select --install` and accept the prompt. |
| `could not reach https://runfoundry.app` | The Mac is offline or a network filter blocks it. Check the connection. |
| `that license key was not accepted` | The key was mistyped. Copy it again with **Copy key**, never by hand. |
| `your plan is not active` | The trial ended or a payment failed. Open **Billing** on your [dashboard](https://runfoundry.app/account). |
| `the download is not out yet, so nothing was installed` | Your release isn't published yet. Nothing is charged before a full week with the download; run the same line the day your dashboard shows it. |
| `Foundry is installed, but the key did not activate` | Usually every Mac seat on the plan is taken. Free one with **Free this seat** under **Billing › Mac seats** on your dashboard, then run `foundry license activate <key>`. |
| `command not found: foundry` | This Terminal window doesn't know `~/.local/bin` yet. Run `export PATH="$HOME/.local/bin:$PATH"`, or open a new window after the [PATH step](https://runfoundry.app/docs/get-started/ai-agent/#install). |

## What happened, from Terminal

Terminal:

```bash
foundry doctor                 # what blocks each phone
foundry status                 # phones, today's plan, warm-ups, last events
foundry watch                  # live results as posts run
foundry incidents              # every failed or unknown post, with screenshots and the log
foundry incidents --resolve ID # after the cause is fixed
```

Hand any incident to your agent as is: it holds the receipt, the log tail and the screenshots, about 2 KB.

## Signing, the Apple hold and your Mac

**Dashboard warns the signing certificate ends soon**

The runner on each phone is signed with your Apple Developer team, and it stops opening the day that signing ends. A free Apple account lasts 7 days, so the warning comes 2 days ahead; a paid team lasts a year, so it comes 30 days ahead. Run `foundry lane up <phone> --team <team id>` for each phone before the date. Open Xcode once first if it asks you to sign in.

**A new phone says Apple hold**

Apple can take 24 to 72 hours to accept a phone added to your team, and the runner can't install until it does. Leave the phone plugged in and run `foundry lane up <phone> --team <team id>` again the next day. The hold clears from the dashboard on its own once the runner installs.

**Phone checks on the dashboard**

Each phone shows paired, Developer Mode, UI Automation, the disk image, iOS version, runner installed and runner answering. They are read about once an hour. A blank check means it couldn't be read, not that it failed.

**Failure reports**

Off by default. Turn them on under **Setup › Your Mac** on your [dashboard](https://runfoundry.app/account). Each failed post or warm-up then saves a small screenshot of the phone and the last 300 log lines, scrubbed of keys and passwords. Open one from the **Report** link in **Issues**. Reports are kept 30 days. Turning them off deletes what was waiting on the Mac.

**Keep the Mac awake**

On by default, so posts and warm-ups run on time. Turn it off under **Setup › Your Mac**, or run `foundry keep-awake off` (and `on` to undo). A sleeping Mac posts nothing until it wakes.

**A newer Foundry is out**

The dashboard shows it next to your version. Run `foundry update check` to see it from Terminal, then run your install line again to update. Your phones, accounts and plans stay.

## Where your files are

| What | Where |
| --- | --- |
| Everything Foundry keeps | `~/Library/Application Support/Foundry` |
| Today's plan | `fleet/drip-plan-<date>.json` |
| Receipts | `fleet/<phone>/state/post-receipts/` |
| Logs | `agent-cli/logs/` |

## Reach a person

Use the [support form](https://runfoundry.app/support). It goes straight to the team's inbox and a person answers by email, usually the same day. Name the phone and account, and never send a password or a code.

If it needs hands on the Mac, turn on [support access](https://runfoundry.app/docs/operations/support-access/) and we fix it there.
