Troubleshooting

Symptom-first index — find your error message, get the fix.

Organised by where the symptom shows up. If you are not sure which page applies, scan the table below for the message you actually saw.

Before anything else: make application-ps shows which containers are up, and docker compose logs -f <service> shows why one is not. Most issues resolve from those two commands.

Symptom index

What you see	Page
Stack will not start, containers restart-looping	Common issues
.env not found, missing or empty secrets	Common issues
Port already allocated	Common issues
ModuleNotFoundError: No module named 'apps'	Common issues
Connection refused to FerretDB	Common issues
Call connects but there is no audio	Voice and audio
Audio in one direction only	Voice and audio
Speech is garbled, sped up, or robotic	Voice and audio
Agent will not stop talking when interrupted	Voice and audio
Greeting is cut off, or hold messages never play	Voice and audio
No transcript or recording after the call	Voice and audio
Provider cannot reach /answer	Telephony
/answer returns 400	Telephony
Number will not attach or detach	Telephony
Recording never arrives from the provider	Telephony
Campaign stuck in a state, or paused itself	Campaigns
Circuit breaker tripped	Campaigns
Slot acquisition timeout, phone pool exhausted	Campaigns
Worker not picking up jobs	Campaigns
WSS fails behind a reverse proxy	Deployment
GPU not visible to a container	Deployment
Disk fills during a model build	Deployment
Volume permission errors	Deployment

The pages

• Common issues — startup, environment, ports, imports, health checks.
• Voice and audio — anything you can hear, or cannot.
• Telephony — the provider boundary: webhooks, applications, numbers, recordings.
• Campaigns — the orchestrator, ARQ worker, circuit breaker, and concurrency slots.
• Deployment — TLS, proxies, GPUs, disk, and volumes.

Still stuck

Collect these before opening an issue: the failing command, make application-ps, the last 100 log lines from the affected container, and your .env with every secret redacted.

Related

• Daily operations — health endpoints and which logs matter
• Ports and defaults