Voice agent troubleshooting

The problems people actually hit — nothing dialing, a campaign that will not approve, leads stuck at pending, and features that are gated rather than broken.

Almost every voice problem is one of six things. Work down this page in order: the earlier sections cause the later ones far more often than the other way round.

Nothing is dialing at all

Start here, because it has three very different causes.

Check	What it looks like	What to do
The voice functions are not deployed	The tab says The voice-agent functions are not deployed in this environment yet. Nothing is dialing.	Believe it. Nothing in the admin will change this — contact Zyan support
The emergency stop is on	Preflight reports `emergency_stop_active`	Clear it in Settings → Voice & Telephony, then resume each campaign
Live calling is not armed	Preflight reports `live_calls_disabled`	Live dialing is armed at the platform level, not from Settings

The default runtime simulates calls

Zyan's default voice runtime places no calls to the public phone network. A campaign can be approved, running and apparently healthy while nothing dials. Real calling is armed by Zyan for your workspace — there is no switch for it in the admin portal. Until then use Voice Lab, scenario simulation, or a live usability test to a saved test number.

A campaign will not approve

Symptom	Cause	Fix
The selected agent version is not published	The campaign points at a draft	Open the agent, save the draft, click Publish…, re-select it
The selected product version is not published	The pinned product is a draft	Publish the product version and re-select it
No AI disclosure text is configured	Honest disclosure wording is empty on the agent version	Fill it in under Behavior and turn-taking, then publish a new version
No recording policy is configured for the organization	The workspace policy was never chosen	Set Recording policy in Settings → Voice & Telephony
Transfer is enabled but no destination number is configured	Allow human transfer is on with an empty destination	Set a Destination number, or switch transfer off
Cold consumer AI telemarketing is denied by default policy	Audience classification is consumer cold	Reclassify. There is no in-app override
Approve is greyed out: Run a passing preflight first	No passing preflight exists	Click Run preflight and clear every error
The Approve dialog will not submit with nothing failing	Warnings need the typed acknowledgment	Copy the phrase from the Type “…” to continue label exactly

Leads never leave pending

Read the Block reason column on the campaign's Leads table first — it names the exact check.

Block reason	What it means	What to do
`outside_calling_window`	The lead's local time is outside the window	Nothing is broken; the dialer defers. Widen the window or fix the Timezone fallback
`cooldown_active`	The retry cooldown has not elapsed	Wait, or lower Cooldown (min)
`max_attempts_reached`	The lead used all its attempts	Raise Max attempts for future leads; this one is done
`daily_cap_reached`	The campaign hit its daily cap	Dialing resumes on the next allowed day, or raise Daily cap
`lead_suppressed`	The number opted out or is do-not-contact	Suppressed leads are never dialed. Remove them
`wrong_number`	The number was recorded as wrong	Correct the lead's number first
`no_consent` / `consent_expired`	A consent-backed campaign with no valid consent for that lead	Attach consent with evidence, or remove the lead
`invalid_destination`	The number is not valid E.164	Fix or remove the number

A whole roster stuck outside the calling window is a timezone problem

If it is mid-morning your time and every lead reads outside_calling_window, the leads have no timezone of their own and your Timezone fallback is wrong for them.

The agent will not publish or behave

Symptom	Cause	Fix
Publishing is blocked by a validation error	A named field is invalid	The error names the field — Identity and demeanor, AI disclosure wording, Opening line, Workflow, Transfer settings and the rest
The configuration panel refuses to render	The raw JSON behind the panel is malformed	Fix the raw JSON before using structured settings — they are the same record
The agent talks over people	Interruption sensitivity is too low; 1 prevents barge-in entirely	Raise it. The default is 4
The agent waits awkwardly before speaking	Workspace Human timing defaults, or a per-agent override	Adjust Advanced voice behavior defaults, or clear the agent's override
Turn detection false-triggers constantly	Energy-based detection picks up phone-line echo and noise	Switch to Semantic, or arm noise cancellation
Stage budgets are not enforced	Workflow-supervised voice runtime is off	Turn it on in Settings; it applies to new calls
A published agent changed under you	Publishing a new version archives the previous one	Use Edit as new draft so the live version keeps running while you work

Features that are gated, not broken

These are limits, not faults

Call recordings are not built. The Recording policy selector exists and preflight enforces it, but no audio is captured. Use the transcript.
Warm transfer is not available. It is selectable in the agent editor and labelled as not yet available — it falls back rather than warm-transferring. Use Cold transfer.
External verified caller ID is experimental and limited to test-mode campaigns. It produces external_caller_id_forbidden unless a platform flag is on.
Live PSTN dialing is armed at the platform level, never from Settings.

Symptom	Cause	Fix
No Voice Agents item in the sidebar	The workspace is on the Base plan — the item is hidden and a deep link shows a plan notice	Talk to the workspace owner about the plan
The workspace loads but you cannot edit anything	You have `voice` but not voice edit permission	Ask an owner to grant it
You cannot run a preflight	Running one needs voice edit permission	Ask someone with it to run one; results are then visible to you
The Twilio and Telnyx cards show no connect form	Connecting is owner-only, or the provider is paused from its tile	Ask the owner, or turn it back on under Settings → Integrations

Anything else

Symptom	Cause	Fix
Preflight passed, launch was still refused	Preflight re-runs at launch and something changed	Run it again and read the new rows
A clean preflight but no real calls	The mock runtime skips the caller-ID and live-call checks	A clean preflight on the mock runtime is not proof of live readiness
A call is listed as preflight blocked	A per-dial check stopped it	Open the check reference and the lead's block reason
The outcome on a finished call is empty	Extraction runs after the call ends	Reload in a moment; basic extraction always runs
A lead's CRM status did not move	CRM status sync is off, or the outcome was not terminal	Check the toggle and the call's CRM projection panel