I exported a fresh batch of wallpaper assets as WebP and attached them to an agent, expecting it to catch the inconsistencies in my file naming. What came back was silence. No error, no complaint — the attachment simply had not happened.
Later that week I handed over a sound effect from one of my calming apps as .opus, and the model replied that it could not handle the format. Both files open fine in any player on my machine.
Two different symptoms, but the same layer was responsible. Not the bytes in the file — the MIME type the sending side decided to stamp on it.
Hub 2.9.1, released August 20, added WebP attachments. CLI 1.1.17, released the same day, fixed .ogg, .opus, and .ogv being sent as the generic application/ogg and rejected by the model. The hub has widened its attachment intake several times since then. Knowing why the failures happened is still more useful than knowing they were fixed, because the next file that stalls will have a different extension.
The question this piece answers is narrow: when a file you attached never reaches the agent, or reaches it and gets ignored, where should you look first?
Start by deciding which layer dropped it
The instinct when an attachment goes missing is to re-export it in another format. That is the long way around. Decide which layer dropped it first.
| Layer | What you see | What to check first |
|---|---|---|
| 1. Client and version | Nothing happens, or a format or size error notification appears | Your hub / IDE / CLI version and the formats and limits that version accepts |
| 2. MIME resolution | The attachment goes through, but the model says it cannot use it | What your own machine resolves the file to (both ways, below) |
| 3. Delivery path | The turn gets heavy, or only a reference appears | Whether you attached it or an MCP server returned it |
Layers 1 and 2 look almost identical from the outside, and the difference is whether anything at all landed in the conversation. If the agent acknowledges a file and then declines to use it, the intake worked and the type is wrong. If the conversation stays empty, the intake never happened. That single observation decides which half of this article applies to you, and it costs nothing to make.
My two failures were layer 1 and layer 2 respectively. WebP had no intake at all on hub builds before 2.9.1. Opus had an intake, but the type stamped on it was too coarse to be useful. The Windows bug where attaching images or media files made the agent fail also sat in layer 1, and was fixed in IDE 2.5.5 on August 13.
A symptom-by-symptom triage table
The changelog for the last three months carries a surprising number of attachment fixes. These are the ones I hit, or nearly hit, with how to confirm each. Versions and dates are as of November 2026, checked against the official changelog.
| Symptom | Likely cause | How to confirm | Fix |
|---|---|---|---|
| A WebP attachment leaves no trace in the conversation | Hub older than 2.9.1 has no WebP intake | Check the version in Settings | Update to 2.9.1 or later |
| Nothing happens and no error is shown | Before 2.9.1, size, count, and format failures raised no notification | Check the version, then repeat the action after updating | Update and act on whatever the notification says |
The model refuses .opus or .ogv | Sent as generic application/ogg (fixed in CLI 1.1.17 and hub 2.11.0) | Check both the CLI and hub versions | Update both. If you are in a hurry, re-export Opus as M4A |
| After attaching an empty text or JSON file, every later message fails | Empty-file attachment bug (fixed in hub 2.33.0) | Check whether the file is 0 bytes | Update, or restart in a new conversation |
| A large WebP opened by the agent fails on size limits | Not downscaled the way PNG and JPEG were (fixed in CLI 1.2.15) | Check the CLI version and the image dimensions | Update. If you are in a hurry, shrink the long edge first |
| An MCP image or PDF shows only a reference | Not a bug: large binaries are saved to a file (hub 2.9.1 onward) | Check that the referenced file exists | Nothing. Open the reference if you need it |
Layer 1 goes away when you update. Layer 2 is the awkward one, because it can come back on a different machine even after you have updated. The next section shows why.
Two ways of resolving the type, side by side
There are two ways to decide a file's MIME type: sniff the leading bytes, or look the extension up in a table. I ran both against the same set of files.
# Resolve from content (magic bytes)
for f in sample.png sample.webp sample.ogg sample.opus sample.ogv; do
printf '%-13s %s\n' "$f" "$(file -b --mime-type "$f")"
doneOutput on Ubuntu 22.04 with file 5.41:
sample.png image/png
sample.webp image/webp
sample.ogg audio/ogg
sample.opus audio/ogg
sample.ogv audio/ogg
Now the extension table:
import mimetypes
for name in ["sample.png", "sample.webp", "sample.ogg", "sample.opus", "sample.ogv"]:
print(f"{name:<13} {mimetypes.guess_type(name)[0]}")Output on Python 3.10.12:
sample.png image/png
sample.webp None
sample.ogg audio/ogg
sample.opus audio/ogg
sample.ogv video/ogg
Line them up and two separate holes appear.
| File | From content | From extension | What happens |
|---|---|---|---|
sample.webp | image/webp | (nothing) | Table-based code assigns no type and sends a generic byte stream |
sample.opus | audio/ogg | audio/ogg | Both agree, but the fact that it is Opus is lost |
sample.ogv | audio/ogg | video/ogg | Audio and video disagree |
All three Ogg-family files start with the same four bytes: 4f676753, which spells OggS. When audio and video share a container, no amount of byte sniffing will separate them. That is the plain reason a content-sniffing implementation lumped the whole family into one coarse type.
WebP fails from the opposite direction. There is no row for it in the extension table on this system, so no type gets assigned, and code that finds nothing usually falls back to a generic byte stream. From the model's side, nothing arrived that claimed to be an image, so declining to look at it is the correct behavior.
Why Opus collapses into plain Ogg: the machine's table wins
This was the part that held me up longest. Python's built-in table does know .opus as audio/opus. Run initialization, though, and the value changes underneath you.
import mimetypes
print(mimetypes.types_map.get(".opus")) # before init: audio/opus
mimetypes.init()
print(mimetypes.types_map.get(".opus")) # after init: audio/oggWhat overwrites it is the mapping table installed on the machine. Here are the relevant lines from /etc/mime.types on mine:
audio/ogg oga ogg opus spx
audio/opus
opus shares a row with plain Ogg, and the audio/opus row directly below it lists no extensions at all. The machine's table is read after the built-in one, so it takes precedence.
The practical consequence is that identical code produces different results on different machines. An attachment that worked on your workstation gets a different type inside a slim container or a CI runner that ships a different mapping table. As an indie developer moving between a work machine and a build environment, that gap is exactly the kind of thing that eats an afternoon.
The detour I took, and the rule I keep now
At first I suspected only the file. I went back to the export settings again and again and re-exported with different options. The results were not encouraging. Every version played fine locally, so comparing them told me nothing.
What finally turned me around was seeing the work machine and the build environment disagree about the same file. Not a byte of it had changed. Only the mapping table reading it was different.
These days, when an attachment stalls, I check the version and the type resolution before I touch the file. Doubt the file only after you have lined up both of the machine's answers. Since I started keeping to that order, re-exporting has almost stopped eating my time.
Three misconceptions worth correcting
"If file agrees, that is the type that gets sent." Not necessarily. file only looks at content. The type a client actually stamps depends on whether its implementation prefers the extension, the content, or a table of its own. Your local check tells you how your machine sees the file, not what goes on the wire.
"The Python version doesn't matter." It does. CPython's built-in table gained .webp as image/webp in 3.11. Up to 3.10, if the machine's table has no row, you get None. Part of the reason WebP resolved to nothing above is that I was on 3.10. Run the same script on 3.11 or later and the WebP line should read image/webp.
"Anything can be attached now, so formats no longer matter." Hub 2.28.0 (October 27) lets you attach files of any type up to 20 MB, and files that used to be rejected for their format are now attached as files that the agent reads from where they are saved. Nothing bounces anymore — but that makes it harder to tell whether an image or audio clip went to the model directly, or was parked as a file for tools to read. In the second case you may want the model to look at a picture and find it only handling the filename.
Re-export, declare the type, or wait for the update
For a file that trips the local check, there are three moves. Which one fits depends on how urgent the handoff is and whether you will keep using the format.
| Move | Good when | Cost |
|---|---|---|
| Re-export to a well-covered format (WebP→PNG, Opus→M4A) | You need it handed over today and have no stake in the format | Larger files, and you learn nothing about the original format |
| Declare the type in your own script or MCP server | You send the same format repeatedly through your own path | Has to be fixed per path, and does nothing for direct attachments |
| Update the client and wait | The fix is already listed in the changelog | Builds roll out gradually and can take several days to arrive |
My own habit: if the changelog lists a fix, I wait for the update and hand over a re-exported copy in the meantime. If the problem only occurs on my own path, I declare the type there. Updates for direct attachments, explicit types for my own pipelines. That one sentence is how I sort it when I am unsure.
Files from MCP servers are typed by someone else
The third layer. Attachments are not the only way a file reaches the agent; an MCP server can hand back images or PDFs too.
On that path the type is declared by the server, not resolved by your client. Aligning your local resolution changes nothing. So the triage order has to start with a simpler question: did I attach this file, or did a tool return it?
Hub 2.9.1 changed how large binaries from connected MCP tools — images, PDFs, and audio — are handled. Instead of being pasted inline, they are written to a file and referenced from the conversation. Previously they could overflow the turn and break it outright. If you see a reference with no visible content, that is not a defect — that is the storage behavior doing its job.
If the MCP server never starts in the first place, you are one step earlier than any of this. I covered that case in Find the one broken MCP entry before Antigravity starts, with a Node script under 60 lines.
A short check before you attach
Layer 2 can be cleared out before the file ever leaves your machine. This script compares both resolutions and surfaces disagreements and gaps.
#!/usr/bin/env python3
"""Compare content-based and extension-based MIME resolution for files you plan to attach."""
import mimetypes
import subprocess
import sys
# Extensions that content sniffing cannot separate, so agreement can still be too coarse
COARSE = {".opus": "audio/opus", ".ogv": "video/ogg", ".oga": "audio/ogg"}
def by_content(path):
try:
r = subprocess.run(["file", "-b", "--mime-type", path],
capture_output=True, text=True, check=True)
return r.stdout.strip()
except (subprocess.CalledProcessError, FileNotFoundError):
return None
def main(paths):
flagged = 0
for p in paths:
ext = "." + p.rsplit(".", 1)[-1].lower() if "." in p else ""
by_ext = mimetypes.guess_type(p)[0]
by_con = by_content(p)
if by_ext is None:
print(f"[no table entry] {p}: extension resolves to nothing (content says {by_con})")
flagged += 1
elif by_con and by_ext != by_con:
print(f"[disagreement] {p}: extension {by_ext} / content {by_con}")
flagged += 1
elif ext in COARSE and by_ext != COARSE[ext]:
print(f"[too coarse] {p}: resolves to {by_ext}, should be {COARSE[ext]}")
flagged += 1
else:
print(f"[match] {p}: {by_ext}")
print(f"--- {flagged} to review out of {len(paths)} ---")
return 1 if flagged else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))Run against the same five files on Python 3.10.12, it reports:
[match] sample.png: image/png
[no table entry] sample.webp: extension resolves to nothing (content says image/webp)
[match] sample.ogg: audio/ogg
[too coarse] sample.opus: resolves to audio/ogg, should be audio/opus
[disagreement] sample.ogv: extension video/ogg / content audio/ogg
--- 3 to review out of 5 ---
The COARSE map exists because agreement and correctness turned out to be different things. Both methods return audio/ogg for .opus. They agree perfectly, and the Opus identity is still gone. If agreement alone were the pass condition, that file would sail straight through.
One caveat on scope: this only settles what your own machine believes. It does not tell you what the client will ultimately put on the wire, and it cannot speak for a file that arrives through an MCP server. Treat a clean run as "layer 2 is probably not my problem right now" rather than as a guarantee, and you will be using it correctly.
The non-zero exit code is there so the check can sit in front of automated steps. Anywhere assets get handed to a machine in bulk — App Store submission prep is my own case — stopping before the handoff beats debugging after it.
Where you are likely to get stuck next: what it costs to hand things over
Once types are sorted, the next question tends to be how much of what you can attach you actually should. I wrote down what I decided not to hand over on the day any file up to 20 MB became attachable in Attachments Went Up to 20MB. Here Is What I Hand the Agent, and What I Keep Back. If you attach CSV or JSON regularly, my measurement of which columns cost the most tokens is in The Date Column Was the Most Expensive Part of My Sales CSV.
How to decide the shape of a multi-machine setup in the first place is something I went into in Choosing a Remote Control Host Machine Comes Down to Daemon Lifetime and Revocation Paths, alongside where credentials end up living. This piece is about the files that actually travel across that setup.
The one thing to try next
Run the files you are about to attach through that script. Only the extensions that come back as [no table entry] or [too coarse] are candidates for losing their type on a machine with a different mapping table. Sort just those into one of the three moves above.
It was a small snag, but understanding it means I can now see the same shape coming. The time I spent re-exporting is gone, but I suspect the next odd extension will cost me far less.