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

FreePBX 17 restored custom macro is missing or returns incorrectly

Find the first divergence among restored custom files, unavailable Macro calls, FreePBX entry points, Gosub targets, argument and variable scope, stack balance, return value and downstream destination.

Reviewed 2026-10-14Sangoma FreePBX 17 migration and platform guidance plus Asterisk 20 Macro semantics and current branch-23 Gosub, Return, LOCAL, LOCAL_PEEK and StackPop documentation reviewed October 14, 2026; Sangoma says the supported FreePBX 17 install defaults to Asterisk 22, where Macro is unavailable and custom dialplan or AGI macro calls require manual conversion, but installed FreePBX, Asterisk, modules, custom files, includes, generated dialplan, subroutine stack, variables, channels, routes and calls remain deployment specific, and no PBX, backup, restore, file, dialplan, AGI script, channel, route or call was inspected or testedAdvancedDocumentation based · not lab tested

Freeze the restored target and one failing path

Record timestamp and timezone, source and target FreePBX and Asterisk versions, backup identity and hash, restore transaction, installed modules, custom-file inventory, Apply Config result, failing number or route, expected destination, actual result, channel identifiers and the first CLI or log error. Keep the restored target isolated from production registration and PSTN routing.

Classify the first mismatch as file absent, include absent, generated configuration not reloaded, Macro application unavailable, stale Custom Destination, missing context or priority, wrong argument, variable-scope change, missing Return, stack imbalance, wrong channel, unexpected hangup or downstream route failure.

Prove that the custom source and include were restored

Compare the archive manifest and restore log with the target path, ownership and content hash. Confirm the supported custom include is actually referenced by the loaded configuration and that Apply Config completed after the source was placed. A file on disk is not evidence that Asterisk parsed or loaded it.

If the file is missing, stop at the archive, module handler, path or restore boundary. Do not recreate remembered dialplan from production traffic or widen filesystem permissions until the owning backup component and expected destination are known.

Locate every obsolete Macro dependency

Search the loaded and source custom dialplan plus AGI code for Macro-family calls and macro- contexts. On the FreePBX 17/Asterisk 22 default described by Sangoma, an unavailable Macro application is an engine compatibility failure, not a trunk or endpoint problem. Preserve the exact line and caller before converting it.

Do not stop after replacing the first Macro() token. Inventory MacroIf, MacroExit, exclusivity, offsets and MACRO_CONTEXT, MACRO_EXTEN or MACRO_PRIORITY use, because each represents a control-flow or state contract that plain Gosub syntax does not recreate automatically.

Trace the Gosub frame, arguments and variable scope

Confirm the caller names an existing context, extension and priority, arguments are inside parentheses, and execution reaches the intended frame on the intended channel. Capture ARG1 onward, reviewed LOCAL() values and any explicitly passed original extension or context.

If a value disappears after Return(), determine whether it was deliberately local. If a nested routine sees the wrong value, record frame depth before using LOCAL_PEEK(). Do not convert all variables to inherited channel state merely to make one branch pass; that can leak stale values into sibling or later call legs.

Prove exactly how the routine exits

Follow every branch to Return(value), a deliberate Goto, hangup or another terminal application. A missing Return() can run into unrelated priorities or leave the caller without its expected continuation. An extra Return or StackPop can remove the wrong frame. Compare the observed return priority and GOSUB_RETVAL with the documented caller contract.

Keep the separate existing Asterisk Gosub diagnostic for generic wrong-channel or stack behavior. Here, first prove whether the symptom begins at the FreePBX restore and Macro-removal boundary before treating it as a new subroutine defect.

Correct one boundary and run a safe acceptance matrix

Correct only the first proven owner: restore content, include, Apply Config, Custom Destination, obsolete Macro call, Gosub target, argument mapping, local scope, exit branch or downstream destination. Repeat the failing route and a known-good control on the isolated target, then test every documented branch and rollback.

A clean CLI trace is not proof of caller experience, media or production interoperability. Record final routing and only reconnect trunks after the normal migration acceptance and change-control gates. No PBX, backup, restore, file, dialplan, AGI script, channel, route 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 · Sangoma FreePBX 17 migration and platform guidance plus Asterisk 20 Macro semantics and current branch-23 Gosub, Return, LOCAL, LOCAL_PEEK and StackPop documentation reviewed October 14, 2026; Sangoma says the supported FreePBX 17 install defaults to Asterisk 22, where Macro is unavailable and custom dialplan or AGI macro calls require manual conversion, but installed FreePBX, Asterisk, modules, custom files, includes, generated dialplan, subroutine stack, variables, channels, routes and calls remain deployment specific, and no PBX, backup, restore, file, dialplan, AGI script, channel, route or call was inspected or tested

FreePBX 17 macro-to-Gosub migration for custom dialplan

Inventory every custom Macro dependency before a FreePBX 17 restore, translate its call and return semantics into explicit Gosub frames, and prove the loaded route without editing generated dialplan.

Read guide →
Guide · FreePBX 16-to-17 migration target and Debian lifecycle evidence reviewed October 8, 2026; FreePBX still directs FreePBX 17 installations to Debian 12.x while Debian 12 is oldstable under LTS through June 30, 2028, and no source PBX, target host, archive, package, module, trunk, endpoint, compatibility or call was inspected or tested

Migrate FreePBX 16 to 17: restore and validate

Plan a separate Debian 12 target, inspect converted SIP objects and rehearse cutover and rollback.

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 →
Troubleshooting · Sangoma PBX GUI 13 Custom Destinations and Misc Applications guides, FreePBX Custom Applications Registry release/17.0 metadata version 17.0.1 and current dialplan source, and current Asterisk Goto, Gosub, Return and dialplan documentation reviewed October 10, 2026; no PBX, module, database row, custom code, generated or loaded dialplan, channel, stack, downstream application or call was inspected or tested

FreePBX custom destination fails, loops or returns wrong: target, stack and branch proof

Trace one call through the selecting module, saved target, generated wrapper, loaded context and runtime Goto or Gosub/Return outcome.

Read guide →
Guide · Asterisk subroutine documentation and Asterisk 22 application references reviewed October 12, 2026; exact application syntax, channel behavior and available functions remain dependent on the installed Asterisk branch and modules, and no PBX, dialplan, channel, stack frame, handler, endpoint, bridge, header, call or media path was inspected or tested

Asterisk Gosub subroutines: stack, scope and channel ownership

Use Gosub and Return while keeping stack frames, arguments, return values and caller- or callee-channel execution independently observable.

Read guide →
Troubleshooting · Asterisk subroutine documentation and Asterisk 22 application references reviewed October 12, 2026; exact application syntax, channel behavior and available functions remain dependent on the installed Asterisk branch and modules, and no PBX, dialplan, channel, stack frame, handler, endpoint, bridge, header, call or media path was inspected or tested

Asterisk Gosub does not return or runs on the wrong channel

Trace one Gosub from invocation and stack frame through arguments, branch, Return, resumed priority and the caller or callee channel that owns its effects.

Read guide →
Guide · Current Asterisk 22 dialplan, CLI, application and hangup-cause documentation reviewed October 1, 2026; no Asterisk host, dialplan, endpoint, trunk, call, media or emergency route was tested

Testing an Asterisk dialplan change safely

Prove context entry, extension matching, priority execution, call-leg outcomes and rollback without treating a successful reload as a successful call.

Read guide →
Hub

VoIP troubleshooting

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

Explore topic →