For installer errors see install. This page covers problems after install. Start with:
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) |
| 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; see presets |
| 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 |
| SMS does nothing | A2P registration not approved, or SMS switch off | See Twilio |
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). 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. |
| 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 #
Plain-text version of this page: /docs/troubleshooting.md. This page is copied from the product's own docs, so it matches the release you install.
Next: Known issues