# Troubleshooting

For installer errors see [install](install.md). This page covers problems after install. Start with:

```bash
npx starwisp doctor
```

A fix for each failing check is printed under it.

## Vault and keys

| Symptom | Likely cause | Fix |
|---|---|---|
| **Test now** fails on a card | Bad paste, expired or revoked key, or wrong scopes | Create a new key following the vendor page, paste again, click **Test now** |
| Anthropic returns 401 | Key copied partly, or billing off | Keys start with `sk-ant-`; check billing at the Anthropic console |
| Anthropic rate-limit errors, runs slow | A new account's low rate limits | Wait or ask Anthropic to raise your tier |
| A card says a key was saved but the run cannot find it | Saved to the wrong repo or typed the wrong field | Re-save in **Settings → Vault**; names are listed on each vendor page |
| A key stopped working after months | Token expiry | Create a new one; vendor pages list expiry notes |
| You pasted a key somewhere public | | Revoke it at the vendor now and create a new one |

## Runs

| Symptom | Likely cause | Fix |
|---|---|---|
| Run says "Paused: this run reached its $X Claude cap" | You hit the factory's Claude per-run cap | Settings → Budget → Claude caps: raise the per-run cap, then **Resume**. The session is saved. |
| Run says "Anthropic spend limit: …" | Your Anthropic org (or workspace) hit the monthly spend limit set in the Claude Console | Raise it at platform.claude.com → Settings → Spend limits, or wait for the date in the message, then **Resume**. The factory never resumes this by itself. |
| New runs wait and do not start | Claude monthly cap reached, or the vendor monthly cap | Settings → Budget: raise it, or wait for next month |
| A stage fails on a missing key | The preset you used needs a vendor you have not set up | Add the key in Vault, or choose a smaller preset (see [presets](presets.md)) |
| A run sits "waiting" | It is waiting on something a human must do (approve, tap Submit) | Open the run page and look for the card that asks |
| The build waits a long time for iOS | Expo free-plan queue | Wait, or move to a paid Expo plan |
| Supabase project count blocked | Free plan allows 2 active projects | Upgrade to Pro or delete an unused project |
| The console says settings could not be saved | Branch rules block direct commits to `main` | Allow the Starwisp App to push to `main` |
| An app's preview address does not load | With a domain: DNS for a new domain has not spread, or the zone ID is wrong. With no domain: the free web address in Identity is not your account's workers.dev subdomain | With a domain, wait a few hours, then check **Zone ID** in Vault. With no domain, press **Test** on the Setup row **Where apps go live** and save the subdomain it names |
| Launch stops: "A Worker named '…' already exists in this Cloudflare account" | No domain: each app's Worker is named after the app, and your account already has a Worker with that name that Starwisp did not make | Rename or delete that Worker in Cloudflare, or build the app under another name |
| Testers never get their sign-in code | No domain: Supabase's built-in sender only reaches members of your Supabase organization | Add a domain and set up [Resend](vendors/resend.md); see [presets](presets.md#a-domain-is-optional) |
| Email from an app is not arriving | Resend domain not **Verified**, or the 100-a-day free limit | Check the domain in Resend; see [Resend](vendors/resend.md) |
| SMS does nothing | A2P registration not approved, or SMS switch off | See [Twilio](vendors/twilio.md) |

## Console

| Symptom | Fix |
|---|---|
| A labelled issue starts no run, or scheduled resumes never run | GitHub did not switch on the factory's workflow triggers: `npx starwisp doctor --fix` (see [install](install.md#if-doctor-fails)). Runs you start from the console still work meanwhile. |
| Console address does not load | `npx starwisp doctor` (it checks the console answers). Then Cloudflare → Workers → `starwisp-console` → Logs. Run `npx starwisp init` to redeploy. |
| A run fails when it creates or reaches the app's repository | The App is probably limited to selected repositories. Open Setup: the row **GitHub App covers all repositories** shows a link. Set *Repository access* to **All repositories** and save. |
| You cannot sign in | You must be a member of your GitHub organization. If you just made the App, finish **Install** with **All repositories**. Check the App's callback URL is your console address plus `/api/auth/callback/github`. |
| Sign-in works then logs you out after hours | GitHub App sign-in tokens last 8 hours and the console renews them. If it can't (you revoked the App's access, or the console was off for six months), it sends you to the sign-in page: click **Continue with GitHub**. Consoles from before release 0.1.1 didn't renew; update, or sign out and back in. |
| A button says "the Starwisp GitHub App needs the permission …" | The App is missing that permission (installs before 0.1.1 have **Actions: read**). Your own role is fine. Grant it under your org's Settings → GitHub Apps → the App → **Permissions & events**, save, then accept it under Settings → GitHub Apps → Installed → the App → **Review request**. See [security](security.md#the-github-app-and-why-it-has-each-permission). |
| Home says "The Idea Studio is off" | The console Worker needs its own copy of your Anthropic key (`ANTHROPIC_API_KEY`); the Setup row **Idea Studio: Anthropic key on the console** gives the exact command. |
| A page times out with many repos | The console limits how many GitHub calls a page makes; reload, and tell support if it persists |

## Stores

| Symptom | Fix |
|---|---|
| The Apple key will not load | It must be the `.p8` file downloaded once from App Store Connect. If lost, revoke the key there and make a new one. |
| Apple says the key's role cannot upload builds | Create a key with the **Admin** role |
| Google says the service account has no access to the app | In Play Console → Users and permissions, invite the service account email with release permissions; wait a few minutes |
| You cannot find the production button in Play | New personal accounts need the 12-tester, 14-day closed test first |
| App Review rejected it | Read the rejection note in App Store Connect. Fix, rerun the relevant stage, and submit again yourself. |

## Still stuck

[support](support.md).