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

ChatCompletions.retrieve (sync) requires a truthy completion_id for GET /chat/completions/{completion_id}. The SDK validates required path parameters client-side and raises ValueError for None/empty values instead of sending a malformed URL.

Source

Thrown at src/openai/resources/chat/completions/completions.py:1380

        extra_body: Body | None = None,
        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
    ) -> ChatCompletion:
        """Get a stored chat completion.

        Only Chat Completions that have been created with
        the `store` parameter set to `true` will be returned.

        Args:
          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(
            path_template("/chat/completions/{completion_id}", completion_id=completion_id),
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                security={"bearer_auth": True},
            ),
            cast_to=ChatCompletion,
        )

    def update(
        self,
        completion_id: str,
        *,
        metadata: Optional[Metadata],
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.

View on GitHub (pinned to 9917c6e28e)

Solutions

  1. Capture the id at creation: `completion = client.chat.completions.create(...)`; store `completion.id` and pass it to retrieve.
  2. Validate the stored id is a non-empty string before calling.
  3. Make sure you pass `completion.id`, not the response object.

Example fix

# before
client.chat.completions.retrieve(completion_id="")
# after
completion = client.chat.completions.create(model="gpt-4o", messages=[...])
stored = completion.id
fetched = client.chat.completions.retrieve(completion_id=stored)
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

When it happens

Trigger: `client.chat.completions.retrieve("")` or passing a completion id variable that is None because the create call's response wasn't captured (`resp.id` missing) or a dict lookup failed.

Common situations: Storing completions for later retrieval but failing to persist `completion.id`; copy-pasting code with the placeholder `chatcmpl-abc123` left empty; passing the whole response object instead of `.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/23f3b90ff50b923e. Report an issue: GitHub.