Troubleshooting

When CARAPACE misbehaves.

The problems below account for ~95% of "I can't get it working" messages. Skim the table of contents, find your symptom, do the fix. If nothing here matches, check the Discord.

Table of Contents

→ Tailscale & HTTPS (most common) → Pairing (iPhone ↔ gateway) → iPhone app → Voice & vision → Mac app → Linux / Raspberry Pi → In-app purchases

Tailscale & HTTPS

Start here — 70% of setup failures are one of these
iPhone can't reach the gateway — pill is red or grey.
Most likely: Tailscale isn't running, or your phone isn't on the same tailnet.
Fix:
  1. On the gateway machine (Mac / Linux / Pi), confirm Tailscale is connected: tailscale status should show logged in.
  2. On your iPhone, open the Tailscale app and confirm the connection toggle is ON.
  3. Make sure both devices are signed into the same Tailscale account. It's easy to have work + personal accounts and accidentally log the phone into the wrong one.
  4. Inside CARAPACE → Settings → tap your gateway. The pill should turn teal within 5 seconds.
"Invalid URL" or chat hangs on every message — HTTPS not enabled.
Most likely: You've paired using http:// instead of https://. iOS App Transport Security blocks plaintext HTTP — your chat stream silently dies.
Fix — enable Tailscale HTTPS (one-time setup):
  1. On your gateway machine, run:tailscale cert && tailscale serve https / http://localhost:PORT where PORT is 1455 for macOS, 18789 for Linux.
  2. Then open login.tailscale.com/admin/dns and enable HTTPS Certificates + MagicDNS.
  3. Regenerate your pairing QR code in the Mac app (Settings → Show QR) or re-run the Linux install script. The new QR includes the https:// URL.
  4. Re-scan on your iPhone.
The Mac app's Setup Wizard step 3 handles this automatically — if you skipped it, re-run the wizard from Settings.
"Connection timed out" after the app was working fine.
Most likely: Your gateway machine went to sleep, lost network, or the daemon crashed.
Fix:
  • Mac: Wake the machine, open System Settings → Battery → disable "Put hard disks to sleep when possible" for the Mac hosting CARAPACE. You can also plug it in so it never sleeps.
  • VPS: SSH in and run systemctl status openclaw-gateway. If it's not active, restart it: sudo systemctl restart openclaw-gateway.
  • Raspberry Pi: Pi SD cards fail under heavy write load. If the service won't start, check dmesg for I/O errors. Move to an SSD if this is recurring.

Pairing iPhone to gateway

QR scan does nothing, or says "Invalid QR code".
Most likely: The QR is from an older install, the gateway URL changed, or HTTPS isn't enabled so the URL is http://.
Fix:
  1. On the Mac app → Settings → Show QR Code regenerates a fresh QR from the current gateway URL + token.
  2. On Linux: re-run sudo carapace show-qr (or the install script — it prints the QR at the end).
  3. If the QR still doesn't work, use Enter Manually on iPhone and paste the URL + token directly.
  4. Make sure the URL starts with https://. If not, go fix HTTPS (see section above).
Paired, but after a minute the app says "No gateway saved".
Most likely: You're on the Solo (Free) tier and have hit the 1-gateway cap, so the new gateway wasn't persisted.
Fix:
  1. Open iPhone Settings → Plan → you'll see "1 of 1 gateway slots used".
  2. Either delete the existing saved gateway first, or tap Upgrade for $4.99 Household (5 gateways).
  3. After upgrading, re-scan the QR — the gateway will now save.
Pill is orange / "degraded".
Most likely: Gateway is reachable but the AI provider behind it is down (no API key configured, quota hit, provider outage).
Fix:
  • On the gateway machine, check ~/.openclaw/openclaw.json — confirm your Anthropic / Gemini / OpenAI key is set and current.
  • Check the provider's dashboard for quota / billing alerts.
  • Try a manual curl https://yourmac.your-tailnet.ts.net/health — it'll tell you which provider is failing.

iPhone app

"No gateway saved" appears even though I just paired.
Most likely: You deleted the active profile and the app disconnected. Or you just re-installed and UserDefaults got wiped.
Fix: Re-pair via QR or Manual Entry. Gateway list is stored per-install; deleting the app wipes it, but IAP unlocks survive.
Pearl is grey and won't turn on.
Most likely: Microphone permission denied.
Fix: iOS Settings → Carapace → Microphone → ON. Also make sure Camera is ON if you want vision mode.
App still shows "CarPlay" as the output after I get out of my car.
Most likely: Stale route-name display. Fixed as of iPhone app v1.6 — update if you're on an older TestFlight build.
Fix: Update via TestFlight. If still seeing it, tap the AirPlay icon next to the output name and pick iPhone manually.

Voice & vision

Voice agent never responds after I speak.
Most likely: The gateway is unreachable or Tailscale dropped. Less likely: music is still playing and drowning the mic.
Fix:
  1. Tap the pearl once to see the connection pill state. Red = fix Tailscale. Orange = fix provider. Grey = not paired yet.
  2. Pause any music / podcasts before the first tap. We auto-pause, but AirPods with ANC sometimes resume on their own.
  3. Make sure you said more than one syllable. The tap + release needs ~400ms of audio to trigger STT.
Music plays while the voice agent is listening.
Most likely: Older TestFlight build. Fixed in v1.6 build 31+.
Fix: Update TestFlight.
Camera shows "Starting camera…" forever.
Most likely: You backgrounded the app mid-session on an older build. Fixed in v1.6 build 24+.
Fix: Update TestFlight. If it still happens, force-quit the app (swipe up in app switcher) and reopen.
Camera is black, or only shows a preview but no AI response.
Most likely: Camera permission denied, or the Gemini Live key isn't configured on your gateway.
Fix:
  • iOS Settings → Carapace → Camera → ON.
  • On the gateway, set GEMINI_API_KEY in ~/.openclaw/openclaw.json. Get a free key at aistudio.google.com.
  • Optionally paste the key into iPhone Settings → Advanced → Gemini API Key as a fallback.

Mac app

Mac app has a blank icon in /Applications.
Most likely: Launch Services' icon cache got stale, usually from installing as a different user.
Fix:
  1. Make sure the app is owned by you:sudo chown -R $(whoami):admin /Applications/Carapace.app
  2. Touch the bundle to bump its mtime:touch /Applications/Carapace.app
  3. Log out + back in to flush the Launch Services icon cache. If it's still blank, re-download the DMG and drag a fresh copy.
Menu bar pearl is there, but Settings won't open.
Most likely: The app was launched without proper entitlements (e.g. you ran an unsigned build).
Fix: Always install from the signed DMG on carapace.info. Quit the app from the menu bar, drag the app to the Trash, re-download, re-install.
Setup wizard keeps saying "Xcode CLI tools not found" after I installed them.
Most likely: Install completed but shell environment wasn't refreshed.
Fix:
  1. Open Terminal and run xcode-select -p. It should print /Library/Developer/CommandLineTools or similar.
  2. If it doesn't, manually run xcode-select --install and wait for the system dialog to finish.
  3. Quit and reopen the Carapace menu bar app — the wizard re-checks on launch.

Linux / Raspberry Pi

Install script exits with "out of memory" or crashes midway.
Most likely: Low RAM on your VPS or Pi. CARAPACE needs ≥2GB RAM; 4GB is comfortable.
Fix:
  1. Add a swapfile:sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
  2. Re-run the install script. It auto-tunes Node's heap based on available RAM.
  3. If you're on a $5/month VPS with 1GB RAM, consider bumping to the $10 tier — 1GB isn't enough for comfortable Claude / Gemini use.
"Systemctl: command not found" during install (container / minimal Debian).
Most likely: You're running inside a container or on a distro that uses a different init system. The install script handles both cases as of v1.9.23 of the Mac app's bundled installer.
Fix: Re-pull the latest installer:curl -fsSL https://carapace.info/install.sh | bash
Gateway service started but port 18789 isn't responding.
Most likely: Firewall blocking the port, or service bound to the wrong interface.
Fix:
  1. Check the service is listening: sudo ss -tlnp | grep 18789
  2. If your VPS has UFW: sudo ufw allow 18789/tcp — but prefer Tailscale (no open ports needed).
  3. On a DigitalOcean / Linode firewall, whitelist Tailscale's CGNAT range (100.64.0.0/10) rather than exposing the port to the public internet.

In-app purchases

Paywall says "In-app purchases haven't loaded yet."
Most likely: Transient network issue, or you're on a TestFlight build while the IAPs are still in App Store review.
Fix:
  • Wait 10 seconds and tap the tier button again — StoreKit retries on each paywall open.
  • If it persists, pull the paywall closed and reopen it.
  • If you just installed: restart the app once so StoreKit picks up fresh entitlements.
Bought a tier on one iPhone — second iPhone still on free.
Most likely: The second phone hasn't synced your Apple ID purchases yet.
Fix: On the second phone, open CARAPACE → Settings → Plan → Restore Purchases. If you're on a different Apple ID, enable Family Sharing in your primary account (Settings → [Your Name] → Family Sharing → Set up → iCloud & App Store Purchases).
Purchase went through but tier still says Solo.
Most likely: Ask-to-Buy approval is pending (child Apple ID), or transaction is in SCA / 3D Secure review.
Fix:
  • Check your email for a "pending approval" notification from Apple.
  • On the parent / paying device, approve the request in Messages or the Family Sharing settings.
  • After approval, CARAPACE's transaction listener picks it up within 30 seconds. If it doesn't, tap Restore Purchases.

Still stuck?

Discord community Report a bug on GitHub

← Back to carapace.info