Container File Mounting

[Jolomi-Tosanwumi]

Title: container_upload block silently ignored when no active container exists — undocumented behavior

---

Problem: missing documentation

When a container_upload block is included in a message payload, the Anthropic API silently ignores it if no container is currently active. No error is raised, no warning is returned, the file simply never gets mounted. This makes it very difficult to reason about whether a file upload actually took effect.

By "active container" I mean one that was either:

• Created by a code execution block in a turn, or
• Explicitly reused by passing a container id in the request payload

Steps to reproduce

1. Upload a file via the Files API and get a file_id
2. Send a message with a container_upload block referencing that file_id, but without passing a container id in the request and without any prior code execution that would have created a container
3. Observe that the API returns a successful response with no error — but the file is not mounted in any container

Expected behavior

One of:

• The API auto-creates a container when a container_upload block is present and no container is active
• The documentation for container_upload clearly states this limitation
• The API raises an error (e.g. 400) indicating that container_upload requires an active container, so the caller can handle it explicitly

Actual behavior

Silent success. The container_upload block is accepted in the payload but has no effect. There is nothing in the API response to indicate the upload was ignored.

Evidence

The BetaContainerUploadBlockParam type in the SDK has no documentation about this constraint:

class BetaContainerUploadBlockParam(TypedDict, total=False):
    file_id: Required[str]
    type: Required[Literal["container_upload"]]
    cache_control: Optional[BetaCacheControlEphemeralParam]

In our application we had to implement an explicit workaround: files are queued and re-injected on every message loop iteration, and the queue is only cleared once we can confirm an active container exists. Without this, files sent via container_upload before a container became active were silently dropped:

Environment

• anthropic SDK version: 0.96.0
• Python version: 3.13.13