Troubleshooting#
Start with /api/health, /api/ready, authenticated /api/ops/status, service
logs and the matching Telnyx event. Preserve call and message identifiers but
redact caller content before sharing diagnostics.
Readiness reports blockers#
Prerequisites: access to runtime logs and the production environment.
Check database reachability, schema drift, default authentication values, Telnyx signature configuration, fake-provider selection and missing live voice keys. Correct one blocker at a time and restart the service.
Verification: /api/ready returns healthy and /api/ops/status shows the
expected schema with no unexplained stale call slots.
The runtime refuses to start after enabling a phone feature#
Prerequisites: the startup log and the deployment's .env.
Phone features are disabled by default and are validated as an ordered chain when the runtime starts. A gap raises a configuration error that names the missing setting, and the process stops rather than starting half-enabled. Enable one step at a time and restart between steps.
| Enabling | Also requires |
|---|---|
| Any phone capability | The phone-system gate |
| Browser credentials | Carrier mutations |
| Browser JWT registration | Browser credentials |
| Outbound browser calling | JWT registration and the call-control gate |
| Inbound browser ringing | JWT registration only — it does not need outbound authorisation |
| Conference-based inbound controls | Inbound browser ringing and the identity gate |
| Voicemail | The identity, phone-system and carrier-mutation gates |
| Queues | Inbound browser ringing and voicemail |
| Recording or conference | Outbound browser calling or conference-based inbound controls |
| Recording | A recording policy version and disclosure text |
Conference-based inbound controls and voicemail also need the TeXML account and application identifiers, the Telnyx public key, the phone authorisation signing secret, and a public HTTPS base URL in production. Queues and voicemail do not need the call-control gate. See Configuration for the setting names.
Verification: the runtime starts, and /api/ready reports no configuration
blockers.
Telnyx cannot start a call#
Prerequisites: the Telnyx event ID and the public runtime URL.
Confirm HTTPS, the TeXML voice URL and method, status callback, assigned number, public-key configuration and reverse-proxy routing. Check that the request was not rejected for size or signature failure.
Verification: a new test call receives a greeting and creates exactly one call record.
The caller hears no response#
Prerequisites: a connected call and provider logs.
Check the media WebSocket upgrade, live speech-to-text and synthesis providers, supported audio format, provider quotas and latency. Fake providers do not validate live RTP behaviour.
Verification: the next call produces recognised speech, audible playback and a completed transcript.
A browser-routed number answers with the assistant#
Prerequisites: the number's routing mode and the browser phone's state.
Inbound browser ringing is off by default. Where it is enabled, a call rings the browser only when the number resolves to exactly one enabled owned extension and browser endpoint, with an unexpired presence lease and a registration whose credential has not expired. No candidate, more than one candidate, an expired presence lease or an expired credential all send the call to the number's configured fallback experience instead of failing, so a call answered by the assistant is the expected outcome rather than an error.
The presence lease is short and is released when the phone tab goes offline, so a closed or reloaded dashboard stops the browser ringing within about a minute. The shared Telnyx SIP username is not an inbound fallback.
Verification: the phone operations view shows one reachable route for the number, and a test call rings the registered browser.
Recording is unavailable or a saved recording will not play#
Prerequisites: the recording settings and runtime logs.
Recording stays unavailable until the recording gate, a policy version, the disclosure text and the number's own recording setting are all present, and the operator attests before capture starts. Playback is served through the authenticated runtime; a provider media link is never returned to the browser. For inbound recording and voicemail media, the runtime downloads only from the exact HTTPS hosts named in the recording media host setting, and it does not follow redirects, so a carrier storage host that is not listed fails closed rather than fetching. Recordings captured on the outbound browser-call path use a separate fetch restricted to Telnyx-owned hosts, so tightening the media host list does not narrow that path. Recordings also become unavailable once their retention deadline passes; the default is 30 days.
Verification: a permitted recording plays from the dashboard, and the runtime log shows no unverified media host.
Local checks pass but the live line does not#
Prerequisites: a deployed production runtime and a phone you can call from.
The local verification suite runs with fake providers on a temporary database. It proves service wiring, not carrier delivery or handset audio. Prove the live path with the read-only Live line acceptance check, which stops on production readiness, routing and messaging-compliance gates before asking for any live phone action.
Verification: a live acceptance run passes and writes its redacted evidence file.
Dashboard login or data fails#
Prerequisites: browser developer tools and both service logs.
Confirm the public and runtime URLs, HTTPS, the web password and distinct session secrets. Clear an obsolete cookie only after confirming the deployment now uses the intended secrets. Verify that the dashboard can reach the runtime without exposing the runtime token to the browser.
Verification: a new authenticated session loads runtime status and a recent call without repeated login prompts.