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

Asterisk include is missing, uses the wrong order or exec output fails

Find the first divergence across configuration root, resolved include set, optional files, wildcard membership, generated command output, section inheritance, parser result, reload and loaded state.

Reviewed 2026-10-26Current Asterisk configuration-file, directory, template, section-extension, GetConfig, UpdateConfig, Reload, AMI-permission and network-security documentation plus the Sangoma FreePBX Configuration File Editor guide were reviewed October 26, 2026; installed branch, astetcdir, include expansion, file order, generator ownership, filesystem permissions, command environment, module parser, reload support, loaded objects and service outcome remain deployment-specific; no PBX, FreePBX system, manager session, file, include graph, external command, generated output, reload, channel, packet, media stream or live call was inspected or testedAdvancedDocumentation based · not lab tested

Freeze one load attempt and one symptom

Record node, build, effective astetcdir, entry file and hash, literal directives, resolved include targets, wildcard membership, file owner and mode, generator owner, target module, reload request, first parser or command error, loaded object evidence and synchronized time.

Classify the first symptom as missing required include, absent optional include, unexpected wildcard member, wrong same-named section, failed or stale exec output, permission denial, parse failure, reload refusal, stale loaded object or wrong service behavior. Do not combine several reloads into one timeline.

Resolve the path before editing content

Confirm the deployed configuration directory rather than assuming /etc/asterisk. For asterisk.conf, resolve includes as absolute paths because that file establishes the relative directories used elsewhere. For other configuration files, retain the parent file, literal target and canonical resolved path.

Check existence, regular-file type, symlink policy, readable owner and hash. A file found by an operator’s shell may still be outside the directory or permissions used by the running Asterisk process.

Distinguish required, optional and wildcard inputs

A missing #include is a load-stopping condition for the affected module configuration; a missing #tryinclude is intentionally tolerated. Do not “repair” an optional absence by creating an empty file unless the owner and desired semantics require it.

For a wildcard, inventory the exact matching files and their hashes at the failed load. Compare that set with the approved manifest and remove only an unauthorized or superseded member. A broad rename can change both membership and later duplicate-section behavior.

Prove exec permission, process and output separately

First confirm whether execincludes is intentionally enabled. If it is not, stop and use a safer managed source rather than enabling code execution merely to clear an error. If it is approved, verify the absolute executable, arguments, service identity, environment, dependencies, exit status, timeout and captured output without exposing secrets.

Then parse the output as configuration and retain its hash. A zero exit status does not prove non-empty, current, trustworthy or syntactically valid output; a valid fragment does not prove the target module accepted it.

Reconstruct effective sections and inheritance

Read the assembled scope around the first wrong object. Preserve source order, duplicate category names, template inheritance and local overrides. For a (+) extension, confirm that qualifiers select the intended object when an endpoint, AoR or another category shares the same name.

Compare literal and effective values. Adding a duplicate setting to the final file can conceal a wrong include or unqualified extension and make the next generated reload less predictable.

Repair the owner, reload once and verify runtime

Correct only the first demonstrated fault in the authoritative source: path, required or optional directive, wildcard manifest, permission, command artifact, template, qualifier or generator model. On FreePBX, use the supported custom-file or GUI path and Apply Config rather than treating generated files as durable source.

Reload the narrowest supported scope once, retain the response and logs, inspect the exact loaded object, and exercise one bounded workflow only when approved. Roll back through the same owner if validation fails. No PBX, file, command, reload, object, 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 Asterisk configuration-file, directory, template, section-extension, GetConfig, UpdateConfig, Reload, AMI-permission and network-security documentation plus the Sangoma FreePBX Configuration File Editor guide were reviewed October 26, 2026; installed branch, astetcdir, include expansion, file order, generator ownership, filesystem permissions, command environment, module parser, reload support, loaded objects and service outcome remain deployment-specific; no PBX, FreePBX system, manager session, file, include graph, external command, generated output, reload, channel, packet, media stream or live call was inspected or tested

Asterisk configuration preprocessor: include, tryinclude, exec and effective order

Trace configuration input across astetcdir, required and optional includes, wildcard expansion, generated command output, duplicate sections, templates, reload and loaded state.

Read guide →
Guide · Asterisk 22 LTS and current Asterisk configuration, CLI, dialplan, module-loader, PJSIP transport and restart documentation reviewed October 5, 2026; exact packaged builds, managed platforms and installed modules require runtime verification

Asterisk configuration lifecycle: source, reload, restart and proof

Trace one change from its supported configuration owner through generated input, loaded runtime state, activation scope, call evidence and rollback.

Read guide →
Guide · Asterisk branch-23-generated and branch-22-generated GetConfig, GetConfigJSON, ListCategories, CreateConfig and UpdateConfig action references plus official configuration-file, template, include, AMI-permission and network-security documentation reviewed October 16, 2026; installed branch, configuration directory, file ownership, generated-file owner, include graph, template inheritance, module parser, reload support, manager privileges and runtime outcome remain deployment specific; no PBX, module, manager session, configuration file, filesystem, reload, channel, packet, media stream or live call was inspected or tested

Asterisk AMI configuration-file inspection and controlled update

Use GetConfig, ListCategories, CreateConfig and UpdateConfig without confusing file content, inherited effective values, a write response, a reload or loaded runtime state.

Read guide →
Troubleshooting · Asterisk branch-23-generated and branch-22-generated GetConfig, GetConfigJSON, ListCategories, CreateConfig and UpdateConfig action references plus official configuration-file, template, include, AMI-permission and network-security documentation reviewed October 16, 2026; installed branch, configuration directory, file ownership, generated-file owner, include graph, template inheritance, module parser, reload support, manager privileges and runtime outcome remain deployment specific; no PBX, module, manager session, configuration file, filesystem, reload, channel, packet, media stream or live call was inspected or tested

Asterisk AMI configuration update is missing, stale or wrong

Trace one intended file change across source and destination, ordered UpdateConfig operations, includes and templates, reload response, loaded module state and service outcome.

Read guide →
Diagnostic · Current Sangoma fwconsole and Asterisk CLI, dialplan and PJSIP troubleshooting documentation reviewed September 27, 2026; no FreePBX, Asterisk or call path lab tested

FreePBX Apply Config failed: isolate generation from reload

Preserve the failed change, capture the supported fwconsole reload error and prove which generated object reached Asterisk before attempting repair.

Read guide →
Guide · Sangoma Custom Destinations, Misc Applications and Misc Destinations guidance; FreePBX Custom Applications 17.0.1 and Misc Applications 17.0.3 release/17.0 metadata and current dialplan sources; and current Asterisk Goto, Gosub, Return and dialplan documentation reviewed October 11, 2026; older screen guides establish concepts rather than an exact FreePBX 17 field map, and no installed module, code, application, destination, generated or loaded dialplan, caller path or call was inspected or tested

FreePBX Custom Destinations: publish custom dialplan without losing ownership

Register a reviewed context, extension and priority as a managed destination, choose transfer or subroutine behavior deliberately, and keep source, generated state and call results separate.

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 →
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 →
Hub

VoIP troubleshooting

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

Explore topic →