openai/openai-python · error · ValueError

Expected a non-empty value for `thread_id` but received {thr

Error message

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

What it means

The sync ChatKit threads retrieve method requires a non-empty `thread_id` for the GET URL `/chatkit/threads/{thread_id}`. The generated guard raises ValueError before any request when the value is falsy.

Source

Thrown at src/openai/resources/beta/chatkit/threads.py:70

        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
    ) -> ChatKitThread:
        """
        Retrieve a ChatKit thread by its identifier.

        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 thread_id:
            raise ValueError(f"Expected a non-empty value for `thread_id` but received {thread_id!r}")
        extra_headers = {"OpenAI-Beta": "chatkit_beta=v1", **(extra_headers or {})}
        return self._get(
            path_template("/chatkit/threads/{thread_id}", thread_id=thread_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=ChatKitThread,
        )

    def list(
        self,
        *,
        after: str | Omit = omit,
        before: str | Omit = omit,

View on GitHub (pinned to 9917c6e28e)

Solutions

Confirm thread_id holds a valid non-empty ID before the call
Trace where the empty value originated (config, DB, previous call)
Double-check you're passing thread_id, not another resource ID

Example fix

// before
thread = client.beta.chatkit.threads.retrieve(thread_id=os.getenv("THREAD_ID"))
// after
thread = client.beta.chatkit.threads.retrieve(thread_id=os.environ["THREAD_ID"])

Defensive patterns

Strategy: validation

Validate before calling

if not thread_id:
    raise ValueError("thread_id is required")

Type guard

def is_valid_thread_id(v: object) -> bool:
    return isinstance(v, str) and bool(v.strip())

Try / catch

try:
    thread = client.beta.chatkit.threads.retrieve(thread_id=tid)
except ValueError as e:
    logger.error("bad thread_id: %s", e)
    raise

Prevention

Use os.environ[...] for required IDs
Double-check ID types before calls (thread vs session vs assistant)

When it happens

Trigger: Calling `client.beta.chatkit.threads.retrieve(thread_id="")` or None on the sync client (threads.py:70).

Common situations: Fetching a thread using an unset env/config value, or passing an assistant_id/session_id by mistake.

Related errors

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