VoIP.infoThe independent guide to business communications.
VoIP.info Troubleshooting

Asterisk AGI script fails or hangs: launch, protocol, dependency and hangup proof

Trace one call through the dialplan application, process or FastAGI connection, AGI dialogue, application result and post-AGI branch without blind retries.

Reviewed 2026-10-10Official current Asterisk AGI overview, Asterisk 23 AGI and EAGI application references, AGI command index, VERBOSE command, AsyncAGI AMI action and events, ASYNCAGI BREAK command and deprecated DeadAGI reference reviewed October 10, 2026; no host, process, executable, service account, FastAGI server, DNS or SRV record, TCP path, AMI session, channel, script, command, audio stream or call was inspected or testedAdvancedDocumentation based · not lab tested

Freeze one attempt and classify the symptom

Record one timestamp, linked ID, channel, context, extension, priority, installed branch, exact AGI application form, script or URI, sanitized arguments and expected next priority. Classify whether the result is NOTFOUND, immediate failure, silence or indefinite wait, an incorrect continuation, a FastAGI connection symptom or a stall that appears only after caller hangup.

Do not retry the call or restart Asterisk before preserving the dialplan and bounded logs. A script failure can resemble an upstream route that never reached AGI, a later application that blocked, or a caller who hung up while the script was still active.

Prove the dialplan reached the intended AGI form

Follow the channel into the exact loaded context, extension and priority and confirm whether it invoked local AGI, EAGI, FastAGI or agi:async. Compare the executed target with the deployed dialplan rather than an edited source file. Capture AGISTATUS immediately after AGI returns and preserve the next dialplan branch.

If AGI never started, remain on dialplan loading, pattern match and application availability. If it started but has not returned, AGISTATUS does not yet exist for that invocation; inspect the active process, connection and command boundary instead of inventing a status.

Prove the local launch boundary

For local AGI or EAGI, resolve astagidir, the final executable or interpreter, owner, mode, mount options, Asterisk service identity, working directory, environment and linked or imported dependencies. Determine whether a process was created and whether it exited, was signalled or remained blocked. For EAGI, include whether the application expected incoming audio on file descriptor 3.

Reproduce only with the service identity and a sanitized non-production input under an approved procedure. Success in an interactive administrator shell does not clear the running service boundary. Correct a single demonstrated path, permission, interpreter or dependency fault; do not grant broad write access or elevate the daemon.

Prove the FastAGI name, connection and service boundary

Resolve the exact agi:// target, or the _agi._tcp SRV lookup used by hagi://, from the Asterisk host. Preserve the selected address and port, TCP result, server acceptance, requested script selector, response timing and any downstream dependency result. Separate DNS or SRV failure, route or firewall failure, connection refusal, application rejection and an accepted connection that never completes the AGI dialogue.

Use a bounded service health check outside a live call only if it exercises the same listener and target without changing state. A successful socket connect is not proof that the selected FastAGI program, its database or its call-side commands succeeded.

Follow protocol progress and hangup behavior

Mark the last complete AGI request and response, then inspect which side is waiting. Keep standard output reserved for the protocol and move incidental application output to a separate log. If temporary AGI protocol debugging is approved, scope it to the shortest reproduction, protect caller data and secrets, and turn it off immediately afterward; use bounded VERBOSE messages for safe script milestones.

For a caller hangup, distinguish local SIGHUP, FastAGI’s inline HANGUP, the process or connection close and any configured AGISIGHUP or AGIEXITONHANGUP behavior. A channel waiting for application cleanup after hangup is not evidence of an unexplained network freeze.

Repair the smallest boundary and retest outcomes

Correct only the proven fault: loaded dialplan, executable path or mode, interpreter, service environment, FastAGI resolution or listener, protocol handling, downstream timeout, hangup cleanup or post-AGI branch. Keep a bounded failure path so one unavailable dependency cannot retain the channel indefinitely.

Retest one success plus missing executable, refused service, slow dependency, malformed response and caller hangup where applicable. Correlate AGISTATUS or AsyncAGI command ID and event result with the next dialplan step and caller-visible outcome. Remove temporary logging and retain sanitized evidence. No host, script, connection, command, audio stream or call was tested for this diagnostic.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

VoIP troubleshooting

Use symptoms and evidence to isolate registration, routing, media and device faults.

Explore topic →
Guide · Official current Asterisk AGI overview, Asterisk 23 AGI and EAGI application references, AGI command index, VERBOSE command, AsyncAGI AMI action and events, ASYNCAGI BREAK command and deprecated DeadAGI reference reviewed October 10, 2026; no host, process, executable, service account, FastAGI server, DNS or SRV record, TCP path, AMI session, channel, script, command, audio stream or call was inspected or tested

Asterisk AGI and FastAGI: bound synchronous call control and external dependencies

Choose local AGI, FastAGI, EAGI or AsyncAGI deliberately; constrain process, network and hangup behavior; and keep launch, protocol, application and call outcomes separate.

Read guide →
Guide · Current Asterisk interface documentation reviewed September 30, 2026; implementation must be checked against the installed branch and integration library

Asterisk AMI, ARI and AGI: choose the control boundary

Separate management events, synchronous dialplan work and application-owned call control before exposing an integration.

Read guide →
Guide · Current Asterisk logging, runtime command, logger.conf, debug-collection, call-identifier and console-verbosity documentation reviewed September 30, 2026; no process, logger, trace, storage path or call tested

Asterisk logging without permanent debug overload

Map configured destinations, console levels, call identifiers and a bounded protocol trace without leaving sensitive debug collection active.

Read guide →
Guide · Asterisk CDR, CEL, Local Channel and AMI v2 documentation reviewed October 6, 2026; no PBX, channel, call, Local pair, optimization event, CDR, CEL event, backend, database, report, billing calculation or retention workflow was tested

Asterisk CDR and CEL: which record answers the question?

Choose a CDR summary or CEL event chronology deliberately, preserve channel relationships and prove the selected record path before using it for billing or operations.

Read guide →
Troubleshooting · Current Asterisk ARI overview, configuration, getting-started, Stasis application, res_ari and outbound-WebSocket documentation reviewed October 6, 2026; exact running branch, build options, modules, configuration, credentials, application process, proxy, WebSocket, dialplan, channel and call require runtime verification

Asterisk ARI Stasis application is not registered: control-path diagnosis

Trace HTTP service, ARI user, WebSocket ownership, exact application name and Stasis lifecycle when a channel immediately leaves an ARI application.

Read guide →
Troubleshooting · Asterisk 22 res_pjsip configuration, current taskprocessor CLI debugging documentation and the project taskprocessor source reviewed October 6, 2026; commands, fields, queue ownership and safe operating limits still depend on the installed branch, modules, workload and support policy

Asterisk taskprocessor queue reached its high-water mark

Identify the alerting taskprocessor, preserve queue depth and timing evidence, and separate the producer, consumer and PJSIP overload response before changing limits.

Read guide →