openai/openai-python · error · ValueError

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

Error message

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

What it means

The sync EvalRun.retrieve() method requires run_id to be non-empty for the path /evals/{eval_id}/runs/{run_id} and raises ValueError before making the request if the value is falsy.

Source

Thrown at src/openai/resources/evals/runs/runs.py:152

        extra_body: Body | None = None,
        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
    ) -> RunRetrieveResponse:
        """
        Get an evaluation run by ID.

        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 eval_id:
            raise ValueError(f"Expected a non-empty value for `eval_id` but received {eval_id!r}")
        if not run_id:
            raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}")
        return self._get(
            path_template("/evals/{eval_id}/runs/{run_id}", eval_id=eval_id, run_id=run_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=RunRetrieveResponse,
        )

    def list(
        self,
        eval_id: str,
        *,
        after: str | Omit = omit,
        limit: int | Omit = omit,

View on GitHub (pinned to 9917c6e28e)

Solutions

  1. Verify run_id came from a successful client.evals.runs.create() call (use its .id).
  2. Log run_id before the call.
  3. Validate persisted ids at load time.
  4. Guard with an emptiness check.

Example fix

# before
run = client.evals.runs.retrieve(eval_id=eval_id, run_id=run_id)

# after
if not run_id:
    raise ValueError(f"run_id is required, got {run_id!r}")
run = client.evals.runs.retrieve(eval_id=eval_id, run_id=run_id)
Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(run_id, str) or not run_id.strip():
    raise ValueError(f"run_id must be a non-empty string, got {run_id!r}")

Type guard

def is_valid_run_id(run_id: object) -> bool:
    return isinstance(run_id, str) and bool(run_id.strip())

Try / catch

try:
    run = client.evals.runs.retrieve(eval_id=eval_id, run_id=run_id)
except ValueError as e:
    if 'run_id' in str(e):
        raise ValueError(f'Cannot retrieve run: {e}') from e
    raise

Prevention

When it happens

Trigger: Calling client.evals.runs.retrieve() with run_id='' or None while eval_id is valid.

Common situations: The run creation response was not stored (run = client.evals.runs.create(...); run_id never extracted), or the id was read from persistence that contains empty values.

Related errors

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