Media error codes (mpbx-media-app, mpbx-media)
Codes raised by mpbx_media_app (W3-MAPP-01, W3-MAPP-02), the in-house media application that plays
prompts, collects DTMF, records voicemail and mixes conference rooms on plain RTP legs anchored through rtpengine (ADR-0004). Kinds
map to HTTP statuses in the API layer as for the common codes. Messages never contain
SDP bodies, addresses, digits, phone numbers or session tokens. See the
mpbx-media guide.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-MEDIA-SESSION-UNKNOWN | not_found | The session, conference or participant handle is unknown, already closed (or left), or its token does not match. One code for all three, so a caller cannot probe for live sessions. | Usually a call-state bug: the call actor used a handle after closing it, or after an mpbx-media restart. Open a new session. |
MPBX-MEDIA-TENANT-MISMATCH | permission_denied | A session, conference or participant handle of one company was used with another company's context (including a join to another company's conference room), or a prompt of another company was passed to play. Nothing was allocated or queued. | A bug or an attack in the calling code: handles and cached prompts must stay with the company that owns them. A conference room never mixes two companies. |
MPBX-MEDIA-CODEC-UNSUPPORTED | invalid_argument | The SDP offers no codec mpbx-media handles. mpbx-media only terminates PCMU, PCMA, G.722 and Opus (DECISIONS Round 10). | Ask rtpengine to transcode the leg towards mpbx-media to PCMU (or G.722 for wideband), as the media-control codec policy does. |
MPBX-MEDIA-SDP-INVALID | invalid_argument | The SDP has no usable audio section: no audio m= line, no connection address, port 0 (rejected stream), an invalid payload type, or a protocol other than plain RTP/AVP. | mpbx-media only talks plain RTP to rtpengine. Pass the SDP rtpengine produced for the mpbx-media leg (ICE removed, no SRTP), not the endpoint's own SDP. |
MPBX-MEDIA-PROMPT-INVALID | invalid_argument | A prompt file is not a usable WAV: not RIFF/WAVE, missing chunks, larger than 32 MiB, or not 16-bit PCM / 8 kHz G.711 at 8 or 16 kHz. | Convert the prompt on upload (W3-TEL-07 transcodes uploads to WAV). |
MPBX-MEDIA-OVERLOADED | unavailable | mpbx-media refused new work: the session limit (media.max_sessions, conference participants included) is reached, a conference room is full (media.max_conference_participants), a worker queue is full, a worker stopped, or no RTP port is free in media.rtp_ports. Retryable. | Add mpbx-media capacity (cores or instances) or widen the port range. Watch mpbx_media_sessions and mpbx_media_tick_overruns_total. |
MPBX-MEDIA-BAD-STATE | conflict | The operation is not valid in the session's state, for example a second voicemail recording while one runs. | Stop the running recording first. |
MPBX-MEDIA-CRYPTO | internal | Encrypting or decrypting a stored recording failed: the file key cannot be opened in this company (another company's file, wrong file id), the file was modified, reordered or truncated, or it is not an mpbx-media encrypted file. | Check that the recording belongs to the company that reads it and that the object was not altered. A wrong install master key shows up as MPBX-SECRETS-* in the log. |
MPBX-MEDIA-CONFIG | config | Bad media configuration: a wildcard or multicast bind_ip, workers outside 1-256, jitter frames outside 1-10, a bad RTP port range, a zero limit, conference participants outside 2-1000, or the service started outside a tokio runtime. | Fix the configuration. bind_ip must be an internal address rtpengine reaches (loopback on a single host). |
MPBX-MEDIA-IO | internal | A socket operation failed (bind, send, spawning a worker thread). | Check the bind address and the process limits (open files, threads). |
MPBX-MEDIA-CODEC | internal | A codec failed to initialise, encode or decode. A corrupt received payload is concealed instead, so this is rare. | Report it with the log line. |
MPBX-MEDIA-PROTOCOL | invalid_argument | The media control connection between the engine and a separate mpbx-media broke the protocol (MVP-GAP-02): a frame failed authentication (modified, replayed, reordered, from another connection), its length is out of bounds, or a message is malformed or unknown. The connection is closed; the calls on it end. | A bug or an attack on the internal network. Check that both ends run the same release, and look for mpbx_media_control_frames_rejected_total. |
MPBX-MEDIA-REMOTE-UNAVAILABLE | unavailable | The engine has no authenticated connection to a remote mpbx-media ([media] mode = "remote"): none of [media] remote answers, the service is shutting down, the control secrets differ, or the connection was lost (the calls that were on it end). Retryable. | Check the mpbx-media service and its logs, and that both have the same MPBX_MEDIA_CONTROL_SECRET. The alert MediaServiceDown fires on mpbx_media_remote_up == 0. |
MPBX-MEDIA-REMOTE-TIMEOUT | unavailable | The remote mpbx-media did not answer a control request within [media] request_timeout_ms, or the request could not be queued in time (back-pressure). Retryable. | mpbx-media is overloaded or the internal network is congested: watch mpbx_media_tick_overruns_total and add capacity. |
MPBX-MEDIA-REMOTE-ERROR | (as reported) | The remote mpbx-media reported an error whose code this engine does not know (a newer release on the other side). The kind is kept. | Run the same release on the engine and on mpbx-media. |
MPBX-MEDIA-ROOM-FULL | conflict | The conference room already has as many participants as its own limit (ConferenceOptions::max_participants, a dial-in room's configured limit; W6-TEL-07) allows. The joiner was not added; the check and the reservation are one step, so two callers can never both take the last place. | Expected when a room is full: the dial-in room plays its "room full" prompt and ends the call. Raise the room's limit if it happens often. |