Skip to main content

​
Troubleshooting: MEDIA_UPLOAD_FAILED

MEDIA_UPLOAD_FAILED is the code returned when a media upload or download fails at the storage or provider hop. It shows up on three surfaces: sending or retrieving WhatsApp media, uploading a file through the file-upload API, and uploading a compliance document (business registration, KYC, 10DLC evidence). The message is the diagnosis surface: it names the stage that failed. Match the stage below, then follow the fix for that stage.

​
1. Decode the stage in the message

The error message always includes a stage phrase. Start there — the message tells you which of the three surfaces exploded and at which step.

​
2. WhatsApp media — resolve and download failures

WhatsApp media moves in two hops:
  1. Resolve — the platform calls Meta’s Graph API to turn a media id into a temporary CDN URL.
  2. Download — the platform fetches the bytes from that URL.
A failure on the resolve hop means Meta did not hand back a URL. The most common cause is a media id older than roughly a month — Meta CDN URLs expire, so re-fetching long-past media fails deterministically. A resolve failure can also be an upstream Graph error (an expired Meta access token, a revoked WhatsApp connection). Retry is useful only for a transient Graph blip; for an expired media id it resolves the same way every time. A failure on the download hop means the URL resolved but the CDN fetch failed (a Meta-side blip). That class is retryable — a bounded retry against Meta is reasonable. If you are sending media outbound to WhatsApp and Meta rejects the upload with its own media error (Meta error 131053 — size or MIME problem), the code is WHATSAPP_MEDIA_UPLOAD_FAILED, not MEDIA_UPLOAD_FAILED — check the exact code in the error payload before following this page.

​
3. The 110 MB size cap on WhatsApp media

WhatsApp’s documented ceilings are approximately: audio 16 MB, video 16 MB, voice 16 MB, image 5 MB, document 100 MB, sticker 100 KB. The platform enforces a single upper bound of 110 MB across all media types so a mis-classified or oversized payload cannot exhaust API memory. When the message says the media exceeds the 110 MB cap, the fix is on the sender side: compress or split the media below the cap, or send a link instead of the binary. Meta’s own ceiling may be lower than 110 MB for non-document types — with attachments above ~16 MB, prefer sending the file as a WhatsApp document.

​
4. Generic file upload — storage faults

If you see this code from the file-upload API, the pipeline is writing the object to the platform’s storage bucket.
  • token refresh failed — a transient workload-identity hiccup on the storage hop. It is safe to retry after a few seconds.
  • bucket '...' not found or permission denied — a persistent storage-configuration fault; a retry fails the same way. This is the platform-side case that needs support (see below).

​
5. Compliance documents — the upload pipeline

Compliance document upload runs four steps in order: encrypt the file, probe the storage bucket, write the object, then record metadata in the tenant’s schema. The message names which step broke:
  • encrypt — DEVOTEL_ENCRYPTION_KEY is missing on the platform pod (a platform-side config fault) or the buffer failed encryption.
  • bucket probe / write — the bucket is missing (platform config) or the API service account lacks write access (platform IAM). Both are platform-side; retrying does not help.
  • DB insert — the file reached storage but the compliance documents table was missing from the tenant’s schema, so the upload reports failure even though the file landed. Support can clear the orphaned file and finish tenant provisioning.
For the platform-side stages, the only customer-side check worth doing is confirming the upload is well-formed (a readable file, a supported MIME type, and a size under the upload cap you set) — then escalate if the stage points decode to a platform fault.

​
6. Retry or escalate

  • Retry when the failure is transient — a Meta Graph or CDN blip on the WhatsApp path, or a token refresh failed on the file-upload path. The platform already retries within the hop; a single manual retry after a short wait usually succeeds.
  • Do not retry when the gate is deterministic — the 110 MB cap, an expired WhatsApp media id, or a message that names a bucket, IAM, encryption key, or missing-table stage. Fix the input or escalate.

​
7. What to give support

Escalate when the stage decodes to a platform-side fault (storage bucket/IAM/encryption, or a missing compliance table) or when a retryable class keeps failing. Include:
  • The full error message — that string is the diagnosis.
  • The document id, file name, file size, and MIME type.
  • The tenant id (Settings → Organization).
  • For WhatsApp: the media id and whether the failure is inbound (retrieving received media) or a new outbound attempt.

​
See also