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

Asterisk PJSIP header list is empty, incomplete or misleading

Trace function availability, INVITE scope, current channel, prefix, unique-name behavior and repeated instances before changing endpoint trust or outbound headers.

Reviewed 2026-10-13Current Asterisk PJSIP_HEADERS and PJSIP_HEADER documentation, Asterisk project source and RFC 3261 reviewed October 13, 2026; PJSIP_HEADERS is documented from Asterisk 16.20.0 and 18.6.0, and installed branch, maintenance release, module, channel topology, request, header set, endpoint policy and dialplan remain deployment specific; no PBX, module, dialplan, channel, request, header, endpoint, provider, packet or call was inspected or testedAdvancedDocumentation based · not lab tested

Freeze the disputed request and exact query

Record timestamp and timezone, installed Asterisk branch and maintenance release, loaded module, endpoint, channel and unique identifiers, SIP method, Call-ID, CSeq, dialplan location, prefix argument, returned list and the expected name or value. Preserve a sanitized message when one exists.

Classify the first symptom: unknown function, empty list, prefix returns nothing, expected name missing, unexpected name present, repeated fields collapsed, wrong value read, wrong channel, non-INVITE expectation or consumer rejected an otherwise correct result.

Separate availability from an empty result

Confirm the running release meets the documented 16.20.0 or 18.6.0 floor and that res_pjsip_header_funcs is loaded. Verify the active channel is PJSIP. If the function is unavailable, correct the supported version or module boundary before interpreting any list.

If the function exists, keep troubleshooting at the message and channel layer. Reinstalling or changing endpoint policy does not explain a prefix mismatch or a query executed on a different request.

Prove the current message is the intended INVITE

Correlate the dialplan execution with the inbound INVITE by timestamp, Call-ID, CSeq and channel. REGISTER, OPTIONS, an outbound callee INVITE, a SIP response or a later in-dialog request is outside the documented inventory scope. Local channels, transfers and new outbound channels can move execution away from the original PJSIP request.

Do not use PJSIP_HEADERS() to prove what Asterisk emitted. Use the outbound-header workflow and a bounded wire capture for that question; use the response-header workflow for an answered outbound INVITE response.

Compare unfiltered and prefix-filtered lists

Run the same request through an unfiltered inventory and the smallest intended prefix. Preserve both literal results. If the name appears only in the complete list, correct the prefix or the consumer comparison rather than adding another header.

Apply SIP case-insensitive name comparison deliberately, and account for RFC 3261 compact forms where applicable. Do not silently rewrite unknown custom names or assume every downstream store preserves the same casing and separators.

Read values and repeated instances separately

A single inventory entry does not mean the INVITE contained one field row. Use PJSIP_HEADER(read,name,number) for the intended inbound value and explicit instance, then compare it with the sanitized request. Preserve ordering where the field definition makes it significant.

An empty selected value can mean the instance is absent even when the name exists. A present value does not validate its syntax, sender trust or suitability for routing, identity, emergency or billing logic.

Correct one boundary and repeat a control

Correct only the demonstrated boundary: supported release, loaded module, PJSIP channel, INVITE timing, prefix, name normalization, compact-name handling, instance number or consumer validation. Repeat the same authorized request and a control without the optional field.

Remove temporary full-header logging and retain only approved identifiers and values. Do not copy the inbound inventory wholesale to an outbound request or weaken endpoint identification to make a field appear. No PBX, module, dialplan, channel, request, header, endpoint, packet or call was inspected or 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

Guide · Current Asterisk PJSIP_HEADERS and PJSIP_HEADER documentation, Asterisk project source and RFC 3261 reviewed October 13, 2026; PJSIP_HEADERS is documented from Asterisk 16.20.0 and 18.6.0, and installed branch, maintenance release, module, channel topology, request, header set, endpoint policy and dialplan remain deployment specific; no PBX, module, dialplan, channel, request, header, endpoint, provider, packet or call was inspected or tested

Asterisk PJSIP inbound header inventory: names, prefixes and instances

Enumerate unique header names from the current INVITE, then read the intended value and repeated instance without treating a name list as a packet capture.

Read guide →
Guide · Current Asterisk PJSIP header, inheritable-header, header-list, header-parameter, response-header and pre-dial-handler documentation reviewed October 8, 2026; PJSIP_INHERITABLE_HEADER is documented from 20.19.0, 22.9.0 and 23.3.0, and no PBX, dialplan, channel, header, provider, endpoint, request, response, registration, authentication exchange, availability, compatibility or call was inspected or tested

Asterisk PJSIP outbound headers: channel ownership, inheritance and proof

Put a required SIP header on the channel that will send it, distinguish direct from inherited headers and verify the emitted request.

Read guide →
Guide · Current Asterisk PJSIP_RESPONSE_HEADER, PJSIP_RESPONSE_HEADERS, pre-bridge-handler and Dial documentation plus the project source implementation reviewed October 13, 2026; the functions are documented from Asterisk 16.28.0, 18.14.0 and 19.6.0, and installed branch, maintenance release, channel topology, peer response, header set, dialplan and consumer policy remain deployment specific; no PBX, module, dialplan, channel, request, response, header, endpoint, provider, bridge or call was inspected or tested

Asterisk PJSIP response headers: channel, answer and pre-bridge timing

Read named headers from the answered outbound INVITE response on the callee PJSIP channel without confusing request headers, provisional responses or caller state.

Read guide →
Diagnostic · Current Asterisk PJSIP header, inheritable-header, header-list, header-parameter, response-header and pre-dial-handler documentation reviewed October 8, 2026; PJSIP_INHERITABLE_HEADER is documented from 20.19.0, 22.9.0 and 23.3.0, and no PBX, dialplan, channel, header, provider, endpoint, request, response, registration, authentication exchange, availability, compatibility or call was inspected or tested

Asterisk PJSIP required outbound header is missing or duplicated

Trace one outbound request through the caller, callee, handler and header store before changing a trunk or copying inbound data.

Read guide →
Guide · Asterisk Local Channel, ARI channel, AMI v2 and CDR documentation reviewed October 6, 2026; exact behavior remains dependent on the installed Asterisk build, dialplan, applications, channel technologies, bridges and record backends, and no PBX, Local channel, queue, callfile, channel variable, bridge, event, record, endpoint, media path or live call was inspected or tested

Asterisk Local channels: pairs, optimization and retained behavior

Use Local channels for internal dialplan legs while distinguishing their two halves, default optimization, retained behavior, bridge events and call-record evidence.

Read guide →
Protocol reference

SIP INVITE explained

Read the request that starts or changes a session and identify the point where call setup fails.

Read guide →
Guide · Wireshark 4.x / current upstream tool documentation; inspect installed versions

VoIP packet-capture methodology

Select interfaces, time windows and paired capture points that distinguish network loss from missing evidence.

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 →