Freeze one prompt and one observed result
Record the Asterisk instance and version, exact case-sensitive sound ID, expected language and format, full and filtered ARI results, configured astdatadir, file deployment or package revision, last sounds-index refresh, channel ID and language, playback media URI and state, channel codec, translation evidence and authorized listener result. Retain timestamps and redact call data.
Classify the symptom: exact ARI lookup is absent, the ID appears without the required pair, a newly deployed file is absent from ARI, the wrong language is selected, an unexpected format is used, playback fails to start, playback finishes but is silent, or the spoken content is wrong. Those failures have different owners.
Compare exact and filtered ARI inventory
Query the exact soundId, then list with the expected lang and format filters. Preserve letter case and path-like ID components. Inspect every returned FormatLangPair and do not use optional text as proof of the file's actual speech.
If the ID is absent, stay with deployment and index state. If the ID exists but the pair is absent, stay with language and format packaging. If the exact pair is present, stop copying files and move to channel resolution, translation and playback. Compare each cluster member independently rather than assuming one successful node represents the pool.
Reconcile the configured directory and in-memory index
Resolve the effective astdatadir and its sounds subtree instead of assuming the common path. Compare the expected language directory, basename, extension, ownership, permissions, readable file and package or release manifest on the same Asterisk instance that served ARI. Do not change permissions broadly or restart the PBX merely because one file exists on another node.
Because ARI queries the in-memory sound index, a correct new file can remain undiscoverable until sounds are re-indexed. After validating the file deployment, perform the documented bounded module reload sounds action under the site's change policy and repeat the exact ARI query. Preserve the before-and-after inventory.
Follow the channel-language fallback chain
Read the actual channel language for the failing call. Expand the documented fallback chain from the most specific underscore-separated value through broader variants and the base sounds directory, then compare the first matching prompt with the intended localization. A valid broader fallback can explain audible but unexpected language without any ARI or playback-control fault.
Correct the channel-language owner, directory structure or missing localized prompt that the evidence identifies. Do not rename every language directory or force the server default to repair one trunk, endpoint, dialplan path or ARI-created channel. Retest an intended specific language and one deliberate fallback.
Separate available format from chosen and decoded media
Compare the Sound format pairs with the channel codec and current translation paths. Asterisk may choose the available representation that is easiest to convert for the call. Confirm the necessary format and codec modules are loaded and use current translation evidence before attributing a silent prompt to ARI discovery.
Then follow the ARI playback diagnostic through target ownership, queued or playing state, events, media frames and listener result. An ARI Sound object does not prove the playback request used the expected URI, that decoded frames reached the target or that the file contains the intended audio.
Correct one layer and retest the release boundary
Correct only the proven layer: release manifest, target instance, astdatadir, file placement, permissions, sounds-index refresh, language pair, fallback hierarchy, channel language, format package, codec or translation module, playback URI or target media path. Avoid changing package, language and codec together; that discards the fault boundary.
Retest exact and filtered ARI queries, every intended node, the specific channel language, one fallback, playback state and an authorized audible result. Remove temporary files and logging, record the media revision and rollback, and retain content hashes outside ARI. No sounds directory, prompt file, channel, translation path, playback or call was inspected or tested for this guide.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk 22 ARI Sounds REST API ↗
- Asterisk 22 ARI REST data models ↗
- Asterisk ARI media guide: playbacks and the sound index ↗
- Asterisk sound-prompt searching by channel language ↗
- Asterisk sound prompts and format selection ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.