Skip to main content

Troubleshooting

Problems are grouped by symptom. Find the one you're seeing and jump straight to the fix.

Port 8787 already in use​

Symptom: voxa exits immediately with a message like "Port 8787 is already in use, another Voxa may be running."

Fix: This almost always means you already have a voxa process running somewhere, maybe in another terminal tab you forgot about. Either:

  • Stop the other one, or kill any stray process with pkill -f 'server.cli', then run voxa again.
  • Or run a second instance on a different port: VOXA_PORT=8788 voxa.

See configuration reference for VOXA_PORT and every other environment variable.

Voxa says it has a tmux problem / can't start a session​

Symptom: on a call, Voxa says something like "I'm running into an issue with tmux" when you ask it to start or open a session.

Fix: tmux isn't installed on the laptop. Voxa runs every Claude Code session inside tmux, and macOS doesn't ship it. Install it, then ask again on the same call (no restart needed):

brew install tmux

voxa also warns about this at startup, and the curl installer installs tmux for you on machines with Homebrew.

Claude Code CLI not found​

Symptom: a session starts but immediately shows command not found: claude, or voxa warns at startup that Claude Code is missing.

Fix: install Claude Code and log in once:

npm install -g @anthropic-ai/claude-code
claude

See the Claude Code setup guide for other install options.

cloudflared not found​

Symptom: voxa exits with instructions to install cloudflared.

Fix: This only comes up if you're self-hosting without pointing at a relay, and Tailscale isn't set up either, so Voxa needs its own way to get your phone an HTTPS URL. Install cloudflared with Homebrew:

brew install cloudflared

Then run voxa again. If you'd rather not install cloudflared at all, install and log into Tailscale on both the laptop and the phone instead; Voxa prefers a direct Tailscale connection when it's available and never needs a tunnel in that case. See self-hosting for the full picture.

Tunnel didn't connect after 3 tries​

Symptom: "Couldn't get a working tunnel after 3 tries" and voxa exits.

Fix: Cloudflare's quick tunnel occasionally fails to come up. Just run voxa again, it's a transient network issue most of the time. If it keeps happening, switch to Tailscale instead of the tunnel path: install and log into Tailscale on both devices, and Voxa will use your tailnet directly rather than opening a tunnel at all. See architecture for how the two paths differ.

Phone can't connect / laptop offline​

Symptom: The Voxa app or browser page shows the laptop as unreachable, or a pairing link just spins.

Fix:

  • Make sure the voxa terminal on your laptop is still running. The server has to stay up for the whole session, closing that terminal (or pressing Ctrl-C) shuts everything down, including any in-progress connection.
  • Re-scan the QR code, or reopen the pairing URL printed under it. Both encode a fresh token and pairing code each time voxa starts, so a link from a previous run won't work.
  • If you're on the Tailscale path, confirm both the laptop and phone are logged into the same tailnet.

No call when a task finishes​

Symptom: Claude finishes a task (or gets stuck needing input) and your phone never rings.

Fix: Work through this checklist:

  • Is the phone actually paired? Re-scan the QR code from a fresh voxa run if you're not sure.
  • Did the hook install? Look for a ✓ Claude hook installed line when voxa starts. Without it, Claude has no way to tell Voxa a turn finished.
  • Does the app have notification/call permission? Check iOS Settings for the Voxa app if you've never confirmed this.
  • Have you used up your free calls this month? On the free tier, after 3 calls in a month a finished task shows up as a banner notification instead of ringing your phone. Paid plans always ring; see pricing.
  • Is this project muted? Check ~/.voxa/interrupt_policy.json for mute_finish or mute_blocked set to true, under this project's cwd or under __default__. Those are the two keys the phone's mute toggle writes, and either one turns a call into a quiet notify push. Separately, a project with ring_threshold at 101 or higher stops its finishes ringing (a frozen or broken agent still calls).
  • Was the task actually short? Voxa's defaults are deliberately quiet: a finished turn under about 10 minutes and 15 tool calls stays silent by design, so a genuinely quick task simply never crosses into a ring.
  • Were you at the laptop? A recent prompt typed anywhere in your fleet demotes a would-be ring to a quiet notify push instead, on the theory that you're already there. Check ~/.voxa/hooks.jsonl for the actual reason and why behind any given session, it's the ground truth for all of the above.

The full ring/banner decision logic is in call flow.

Attach says permission needed​

Symptom: Attaching to a terminal fails with a message about Accessibility, and System Settings pops open.

Fix: This happens the first time Voxa needs to control a terminal it can't script directly, Ghostty, Warp, VS Code, or anything else outside tmux/iTerm2/Terminal.app. Go to System Settings > Privacy & Security > Accessibility, and grant access to the terminal app you launched voxa from (not the app you're trying to attach to). Then say "use my open terminal" again.

iTerm2 and Terminal.app work differently: they need macOS Automation permission instead, which macOS should prompt you for automatically the first time Voxa scripts them. If that prompt never appeared or you dismissed it, check System Settings > Privacy & Security > Automation.

Details on the full permission matrix are in terminals.

Two terminals with the same folder name​

Symptom: You asked Voxa to attach to a terminal by folder name, and it landed in the wrong window.

Fix: Attaching by folder name matches the first terminal Voxa finds with that folder as its working directory. If you have two windows open in folders that share the same name (two different myapp checkouts, say), say "list my terminals" first and pick the exact one you want from the list instead of naming it by folder. More on discovery order in terminals.

Screenshot fails​

Symptom: Asking for a screenshot returns an error about Screen Recording permission.

Fix: Go to System Settings > Privacy & Security > Screen Recording, and enable it for the terminal app you launched voxa from. Then ask for the screenshot again.

Mic doesn't work in the phone browser​

Symptom: Using the browser client instead of the app, the microphone never activates or the browser silently blocks it.

Fix: Browsers only allow microphone access over HTTPS. Make sure you're opening the exact pairing URL Voxa printed (it starts with https://), not a bare IP address or an http:// link you typed by hand. The QR code always encodes the correct HTTPS URL, so scanning it directly is the safest option.

Voice session disconnects when idle​

Symptom: The call drops on its own after a few minutes of silence.

Fix: This is by design. To avoid burning minutes on a call nobody's listening to, the voice line auto-disconnects after a period of no speech and no Claude activity, 180 seconds by default. It's controlled by VOXA_IDLE_TIMEOUT; see the configuration reference if you want to change it.

Disconnecting the voice line does not stop Claude. The Claude Code session keeps running on your laptop independent of whether anyone's on the call, and you'll still get called back when it finishes. See architecture for how the session and the voice line stay decoupled.