openai/openai-python · error · ValueError

Expected a non-empty value for `container_id` but received {

Error message

Expected a non-empty value for `container_id` but received {container_id!r}

What it means

The OpenAI SDK requires a non-empty `container_id` to build the upload URL; client.containers.files.create raises ValueError before any HTTP request when it is falsy. The method backs create_and_poll and upload helpers, so those fail the same way.

Source

Thrown at src/openai/resources/containers/files/files.py:92

        You can send either a multipart/form-data request with the raw file content, or
        a JSON request with a file ID.

        Args:
          file: The File object (not file name) to be uploaded.

          file_id: Name of the file to create.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not container_id:
            raise ValueError(f"Expected a non-empty value for `container_id` but received {container_id!r}")
        body = deepcopy_with_paths(
            {
                "file": file,
                "file_id": file_id,
            },
            [["file"]],
        )
        files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
        if files:
            # It should be noted that the actual Content-Type header that will be
            # sent to the server will contain a `boundary` parameter, e.g.
            # multipart/form-data; boundary=---abc--
            extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
        return self._post(
            path_template("/containers/{container_id}/files", container_id=container_id),
            body=maybe_transform(body, file_create_params.FileCreateParams),
            files=files,
            options=make_request_options(

View on GitHub (pinned to 9917c6e28e)

Solutions

Create the container first and pass its id: container = client.containers.create(...); then files.create(container.id, ...)
Assert the container id is non-empty before uploading
Check that the container creation response actually contains an id

Example fix

// before
file = client.containers.files.create(container_id="", file=open('a.pdf','rb'))
// after
container = client.containers.create()
file = client.containers.files.create(container_id=container.id, file=open('a.pdf','rb'))

Defensive patterns

Strategy: validation

Validate before calling

assert container_id, "create the container first and pass container.id"
file = client.containers.files.create(container_id=container_id, file=file_obj)

Type guard

def is_non_empty_str(v: object) -> bool:
    return isinstance(v, str) and bool(v)

Try / catch

try:
    file = client.containers.files.create(container_id=container_id, file=f)
except ValueError as e:
    if 'container_id' in str(e):
        raise RuntimeError('container not initialized') from e
    raise

Prevention

Always create the container before uploading into it
Capture container.id from the create response explicitly
Fail fast on empty config values during service startup

When it happens

Trigger: Calling client.containers.files.create(container_id='', file=...) or the upload/create_and_poll helpers with a missing container id.

Common situations: Uploading into a container whose creation failed or whose id was not captured; using a placeholder string like '' during development.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/c3692925a0ec5bb7. Report an issue: GitHub.