Troubleshooting
errors and their fixes.
Messages you may see, what they mean and what to do, grouped by where they appear. Tip: paste the exact error into the search box. Start every diagnosis with python -m voice check.
01Start and keys
check, serve or dial exits with code 2 and lists settings
Keys are missing. Set every one listed. A .env file is not loaded by itself: set -a; . ./.env; set +a in the same terminal, or enter the keys in the console.
The media server does not start in up / saas
A required key or the NLTK data is missing. Read the start-up notes, run python -m voice setup-nltk, and restart after adding keys.
up ends with "could not open 127.0.0.1:8766 (port already in use?)" and "VOX stopped."
Another process holds the port (for example a second admin). Stop it, or use up --port …; in Docker VOX_ADMIN_PORT=… docker compose up -d.
check reports the profile as missing / PROFILE_UNREADABLE
Run node src/run.js. If the file is damaged, fix the JSON in app/data/profile.json or rename the file and run the questions again. Nothing is overwritten on its own.
Docker: the container keeps restarting, status unhealthy
The console did not start (port in use, bad VOX_ADMIN_TOKEN). docker compose logs vox: the reason is on the last line before VOX stopped.
02Calls
The phone rings, silence after answering, the call drops
The stream never reached the server: the media server is not running, VOX_PUBLIC_HOST is wrong, TLS is broken, or the proxy does not upgrade /ws.
The call connects and hangs up at once; log: "stream for a call this server did not place"
No call plan was found. dial and the server must share one data directory. Calls started from the Twilio console are ignored on purpose.
A third-party call ends right after the start; log: "disclosure failed, hanging up"
The disclosure did not play fully. Check the ElevenLabs key and voice. The call never continues without it, by design.
The bot is silent after the disclosure; LookupError / punkt_tab in the log
NLTK data missing: python -m voice setup-nltk.
A call to your own number runs as third_party
The number is not verified, changed, or has no country code. Verify it in the console. Intended behaviour.
"is not a complete number with an international country code"
Fix the number in the profile or in --to: it needs + (or 00) and the country code.
"Twilio refused the call (401)"
Wrong TWILIO_ACCOUNT_SID or TWILIO_AUTH_TOKEN.
"Twilio refused the call (4xx): …"
TWILIO_FROM_NUMBER must belong to your account. A trial account calls only verified numbers; the destination country must be allowed in the voice geographic permissions.
Webhooks answer 403
The signature does not match. The proxy must not rewrite paths or the host, and VOX_PUBLIC_HOST must equal the public host name.
The assistant is interrupted by "hm" or a cough / jumps in too early
Console → Tuning: barge_in to words:1–words:4 or a higher vad_confidence; a higher silence_timeout_secs if it jumps in before the end of a sentence.
The voice does not speak the call language or sounds wrong
The chosen voice does not handle the language. Pick another ELEVENLABS_VOICE_ID and listen to it on a phone.
03Local speech
"No Piper server answers at …" / "No whisper.cpp server answers at …"
Start the server, check VOX_PIPER_URL / VOX_WHISPER_URL, run python -m voice local-check. VOX does not fall back to ElevenLabs.
"The Piper server … answered HTTP 4xx"
It is the GPL fork's server (JSON API) or the wrong address. Run rhasspy/piper's http_server.
With whisper.cpp the assistant answers late
Recognition starts only after the caller stops talking. Use a smaller model, a GPU build, or ElevenLabs.
04Console
403 BAD_HOST
The browser used another host name. Open exactly the printed URL (127.0.0.1 or localhost).
NODE_MISSING on the briefing
Install Node 20+.
A job stayed failed with INTERRUPTED
The worker stopped while it ran. Submit it again; it is not retried automatically.
Docker: the console does not open from another computer
Intended: it listens only on the host's loopback. ssh -L 8766:127.0.0.1:8766 server.
05SaaS mode
Login works on http but not behind the proxy, or cookies are dropped locally
Session cookies are Secure. Serve through HTTPS; --insecure-http only for local development.
New users cannot log in
No SMTP, so accounts are pending. Activate them in the panel, or configure SMTP.
STRIPE_NOT_CONFIGURED
Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET, then restart.
PLAN_NOT_PURCHASABLE
The plan has no Stripe price ID. Add the price_… ID to the plan.
Paid, but the plan did not change
Webhook not delivered, or the price is not mapped. Check the Payments page (failed deliveries, unmapped price IDs) and the endpoint in Stripe.
Inbound call minutes are not billed
Set the number's "Call status changes" to https://<host>/call/status (how).
Google connect fails with OAUTH_NOT_CONFIGURED
No web client file or no VOX_PUBLIC_HOST (how).
NUMBER_IN_USE when verifying
Another customer verified that number. A number belongs to one customer only.
402 QUOTA_EXCEEDED
The customer's plan limit is used up. Change the plan, grant credits, or wait for the next period.