openai/openai-python · error · ValueError

Expected a non-empty value for `completion_id` but received

Error message

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

What it means

Messages.list (sync) requires a truthy completion_id for GET /chat/completions/{completion_id}/messages. The SDK validates required path parameters client-side and raises ValueError for None/empty values.

Source

Thrown at src/openai/resources/chat/completions/messages.py:83

        Args:
          after: Identifier for the last message from the previous pagination request.

          limit: Number of messages to retrieve.

          order: Sort order for messages by timestamp. Use `asc` for ascending order or `desc`
              for descending order. Defaults to `asc`.

          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 completion_id:
            raise ValueError(f"Expected a non-empty value for `completion_id` but received {completion_id!r}")
        return self._get_api_list(
            path_template("/chat/completions/{completion_id}/messages", completion_id=completion_id),
            page=SyncCursorPage[ChatCompletionStoreMessage],
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                query=maybe_transform(
                    {
                        "after": after,
                        "limit": limit,
                        "order": order,
                    },
                    message_list_params.MessageListParams,
                ),
                security={"bearer_auth": True},
            ),

View on GitHub (pinned to 9917c6e28e)

Solutions

Capture `completion.id` from the create call and pass it to messages.list.
Validate the stored id is a non-empty string before listing.
Confirm you're using the chat completions store API (store=True) so ids exist.

Example fix

# before
client.chat.completions.messages.list(completion_id="")
# after
completion = client.chat.completions.create(model="gpt-4o", messages=[...], store=True)
client.chat.completions.messages.list(completion_id=completion.id)

Defensive patterns

Strategy: validation

Validate before calling

if not completion_id:
    raise ValueError("completion_id must be non-empty")
client.chat.completions.messages.list(completion_id=completion_id)

Type guard

def is_valid_id(value: object) -> bool:
    return isinstance(value, str) and value.startswith("chatcmpl-")

Prevention

Create completions with store=True so ids exist for listing.
Persist completion.id before listing messages.

When it happens

Trigger: `client.chat.completions.messages.list(completion_id="")` or passing a None id from a create response that wasn't captured or a storage lookup miss.

Common situations: Listing stored messages for a completion whose id was never persisted; passing the assistant reply string instead of `completion.id`.

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/37c64b33ffe44c8e. Report an issue: GitHub.