FreePBX music on hold silent or wrong: trace the selected media path

Classify the exact symptom and call path

Record whether the caller hears silence, the wrong category, ringback, early media or remote audio; note who pressed hold and whether the symptom appears in a queue, ring group, inbound route, outbound route, transfer or ordinary endpoint hold. Preserve timestamp, Call-ID, linked channel identifiers, selected destination and both signaling legs. A file that previews in a browser does not prove that the affected channel selected or decoded it.

Sangoma documents Music on Hold categories as selectable inputs to Inbound Routes, Outbound Routes, Ring Groups and Queues. Inspect the effective FreePBX object and generated dialplan without editing generated files. Apply Configuration state and the running Asterisk configuration remain separate evidence.

Prove which music class won

Record the category selected on the relevant FreePBX object, the channel's inherited music class and any explicit Queue, Dial, MusicOnHold, StartMusicOnHold or CHANNEL(musicclass) override. Asterisk documents that the channel value can override an application-level class, while Queue and Dial can name their own class. The label visible on one GUI page is therefore not sufficient proof of the runtime source.

Use Asterisk events and channel evidence to capture the class that actually started. The MusicOnHoldStart AMI event identifies the class and channel; keep it with Uniqueid and Linkedid rather than treating any simultaneous hold event as the affected call.

Validate the source without inventing compatibility

For an uploaded file, record its category, name, container, codec, sample rate, channels, permissions and whether Asterisk loaded it. For an application or streaming source, preserve its configured command, process state, network dependency and exit evidence. Do not replace a licensed production source with an arbitrary Internet stream or copy copyrighted music merely to clear silence.

Asterisk may transcode prompts or music to the channel codec. A successful file decode does not prove adequate CPU capacity, and high CPU does not prove that transcoding caused this call's symptom. Compare one bounded reproduction with the actual negotiated codec and runtime load before changing media formats.

Separate local generation from hold passthrough

With PJSIP, moh_passthrough determines whether Asterisk relays hold and unhold through re-INVITEs or generates music locally; PJSIP_MOH_PASSTHROUGH() can override that behavior on a channel. Confirm the endpoint and channel value before assigning silence to the local category. A remote endpoint or provider that owns the media during passthrough has a different evidence path.

Asterisk also documents that sendonly or inactive SDP can trigger local music and may replace early media when it appears in a 183 response. Preserve the exact offer or answer, dialog state and media direction. Do not globally disable hold handling to fix one early-media case.

Correct the narrow owner and retest

Correct only the demonstrated owner: wrong FreePBX category, a channel override, missing or unreadable source, unsupported file properties, failed source process, transcoding constraint, endpoint passthrough policy or remote hold behavior. Preserve the former configuration, licensing record and rollback trigger. Do not restart production blindly when a bounded reload or supported Apply Configuration path is available.

Use an authorized non-emergency call. Confirm the runtime class, audible source, hold and resume in both directions, queue or route behavior and post-change CPU separately. No PBX, category, file, endpoint, queue, route or live call was tested for this guide.

core show version
module show like res_musiconhold
moh show classes
pjsip show endpoint <endpoint>
core set verbose 4
# Reproduce one authorized non-emergency hold event and retain channel/class evidence.
core set verbose 0

Start from category precedence and source ownership

The FreePBX Music on Hold guide separates inbound-route inheritance, call-target overrides, channel class, local static or streaming source and PJSIP passthrough. Use that order before replacing a file or changing codecs.

Check whether hold was intercepted before changing music files

Use the HOLD_INTERCEPT diagnostic to prove the device signal, event consumer and actual hold action before diagnosing the music source.

Move to the PJSIP hold-path diagnostic when signaling owns the symptom

If the effective PJSIP mode, re-INVITE or remote media owner is disputed, use the focused hold-path diagnostic before replacing local files.