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

Asterisk AMI agent is missing, logoff fails or events do not correlate

Find the first divergence across agent model, module and configuration, list completion, login channel, queue identity, event delivery, soft logoff and the final post-action snapshot.

Reviewed 2026-10-26Current branch-23-generated Asterisk Agents and AgentLogoff actions, agent inventory, login, logoff and queue-call events, AgentLogin, AGENT(), app_agent_pool, AMI v2 and network-security documentation were reviewed October 26, 2026; installed version, app_agent_pool availability, agents.conf, dialplan authentication, queue membership, manager permissions and event filters, live agent channel, device state, call result, recording and FreePBX ownership remain deployment-specific; no PBX, FreePBX system, module, manager account, credential, agent, queue, channel, event stream, recording, packet, media stream or live call was inspected or testedAdvancedDocumentation based · not lab tested

Freeze one node, list transaction and symptom

Record node, build, loaded modules, manager identity, ActionID, action response, every list event, matching completion event, configured agent ID, queue, member name, interface, channel names, Uniqueid, Linkedid, first contradictory event and synchronized time.

Classify the first symptom as action absent, denied action, missing definition, incomplete list, logged-off state, missing login channel, wrong queue member, rejected logoff, active call ended unexpectedly, absent event or mis-correlated call. Do not combine several agents or reconnects into one incident.

Prove app_agent_pool and definition before queue state

Confirm app_agent_pool is present and the agent ID exists in the effective agents.conf. The Agents action reports that pool, while QueueStatus and queue-member events report another model. A queue interface, endpoint, extension or FreePBX agent label is not automatically an app_agent_pool Agent.

If the intended deployment uses dynamic queue members rather than AgentLogin, stop applying the pool diagnostic and follow the queue-member control path. Do not add a duplicate agent merely to make an inventory row appear.

Validate the completed inventory and login path

Repeat one Agents request with a fresh ActionID and wait for its matching AgentsComplete. For AGENT_IDLE or AGENT_ONCALL, validate the returned channel snapshot and stable IDs; for AGENT_LOGGEDOFF, do not require channel fields.

If login is expected, follow the actual dialplan into AgentLogin(), including its separate authentication step and AGENT_STATUS. Confirm the AgentLogin event and fresh completed inventory. A device-state hint or AGENT(status) value alone does not prove the manager list was complete.

Check event authorization, filters and reconnect gaps

Verify that the manager identity can receive the AGENT class and that server- and client-side filters retain the required list and lifecycle events. Capture connection start, authentication, filter policy, reconnects, parse errors, backpressure and sequence around the incident.

A missing AgentCalled, AgentConnect, AgentComplete, AgentDump, AgentRingNoAnswer, AgentLogin or AgentLogoff event can be a delivery or collection fault. It is not proof that the corresponding PBX transition never happened.

Diagnose logoff with active-call semantics intact

Re-resolve the exact agent and current channel immediately before control. Compare the sent Soft policy with the intended outcome: true is documented not to hang up an existing call. Retain the response, any AgentLogoff event, channel and bridge events, call completion evidence and a later completed agent inventory.

Do not retry a non-soft request while the agent is on a customer call. An action acknowledgement, a logoff event, channel disposal, queue-member change and caller outcome are separate observations.

Repair the first owner and verify one bounded call

Correct only the demonstrated owner: module availability, authoritative agent definition, login dialplan, authentication, manager authorization, event filter, queue membership, collector join or logoff policy. Re-login when required for configuration changes that take effect at login, then obtain one completed inventory before a controlled queue call.

Confirm the expected called, connected and completed or no-answer path using both channel IDs, queue, member and interface. Roll back through the same owner if validation fails. No PBX, module, manager session, agent, queue, channel, event stream, recording, packet, media stream or live call was inspected or tested.

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

Guide · Current branch-23-generated Asterisk Agents and AgentLogoff actions, agent inventory, login, logoff and queue-call events, AgentLogin, AGENT(), app_agent_pool, AMI v2 and network-security documentation were reviewed October 26, 2026; installed version, app_agent_pool availability, agents.conf, dialplan authentication, queue membership, manager permissions and event filters, live agent channel, device state, call result, recording and FreePBX ownership remain deployment-specific; no PBX, FreePBX system, module, manager account, credential, agent, queue, channel, event stream, recording, packet, media stream or live call was inspected or tested

Asterisk AMI agent inventory, logoff and call-event evidence

Separate app_agent_pool definitions, agent login state, queue membership, AMI list completion, logoff semantics and per-call events without treating one identifier as the whole state model.

Read guide →
Guide · Asterisk 22 LTS

Asterisk queues: member state, caller outcomes and evidence

Separate queue membership, device state, pauses, call attempts, answered bridges and historical outcomes.

Read guide →
Guide · Asterisk branch-23-generated and branch-22-generated QueueSummary and QueueStatus action references plus official AMI v2, permission and queue documentation reviewed October 16, 2026; installed branch and maintenance release, app_queue version, server identity, manager transport, account, ACL, read and write classes, queue and member names, dynamic membership, event schema, completion behavior, clock, configuration owner, caller state, member reachability, device state and downstream collector behavior remain deployment specific; no PBX, queue, member, caller, manager configuration, account, credential, socket, session, request, response, event series, completion marker, channel, packet, media stream or live call was inspected or tested

Asterisk AMI QueueStatus and QueueSummary snapshots

Collect queue summaries and detailed status as separate, filtered AMI transactions with explicit correlation and completion boundaries.

Read guide →
Troubleshooting · Asterisk branch-23-generated and branch-22-generated QueueSummary and QueueStatus action references plus official AMI v2, permission and queue documentation reviewed October 16, 2026; installed branch and maintenance release, app_queue version, server identity, manager transport, account, ACL, read and write classes, queue and member names, dynamic membership, event schema, completion behavior, clock, configuration owner, caller state, member reachability, device state and downstream collector behavior remain deployment specific; no PBX, queue, member, caller, manager configuration, account, credential, socket, session, request, response, event series, completion marker, channel, packet, media stream or live call was inspected or tested

Asterisk AMI queue status or summary is missing, stale or incomplete

Trace one queue snapshot through target identity, filters, permissions, response correlation, completion, parser behavior and the queue evidence that owns the disputed fact.

Read guide →
Troubleshooting · Current branch-23-generated and branch-22 QueueAdd, QueueRemove, QueuePause and QueuePenalty action references, current QueueMemberAdded, QueueMemberRemoved, QueueMemberPenalty and QueueMemberStatus event references, the branch-22 QueueMemberPause event reference, and the AMI v2 specification reviewed October 17, 2026; action response, queue and interface scope, membership event, pause or penalty event, later snapshot, device state, ringing, bridge, answer and caller outcome remain separate evidence boundaries; installed branch, loaded app_queue module, queue strategy, manager permissions and filters, generated FreePBX configuration, persistence and endpoint behavior remain deployment specific; no PBX, module, queue, member, configuration, manager account, session, event stream, endpoint, packet, audio or live call was inspected or tested

Asterisk AMI queue-member control is accepted but agent state is wrong

Trace one disputed add, remove, pause or penalty change through exact scope, action response, event visibility, later queue snapshot, eligibility and call outcome.

Read guide →
Troubleshooting · Current Sangoma queue documentation and Asterisk queue interfaces reviewed September 27, 2026; installed module and Asterisk behavior remain version-sensitive, and no queue, agent, endpoint or call was tested

FreePBX queue agent does not ring: prove eligibility before changing strategy

Trace one queued call through membership, login, pause, device state, wrap-up and queue policy before changing agent or capacity settings.

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 · Operational guidance; Asterisk 22 / FreePBX 17 where applicable

Least privilege for PBX users and integrations

Separate the right to register, place calls, administer the PBX and read sensitive data.

Read guide →
Hub

VoIP troubleshooting

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

Explore topic →