openai/openai-python · error · TypeError

max_retries cannot be None. If you want to disable retries,

Error message

max_retries cannot be None. If you want to disable retries, pass `0`; if you want unlimited retries, pass `math.inf` or a very high number; if you want the default behavior, pass `openai.DEFAULT_MAX_RETRIES`

What it means

The OpenAI Python SDK raises this ValueError when await client.vector_stores.file_batches.create() (async) is called with a falsy vector_store_id. Since the batch is a sub-resource of a vector store, a valid 'vs_...' identifier is required to build the POST /vector_stores/{vector_store_id}/file_batches URL.

Source

Thrown at src/openai/_base_client.py:415

        base_url: str | URL,
        _strict_response_validation: bool,
        max_retries: int = DEFAULT_MAX_RETRIES,
        timeout: float | Timeout | None = DEFAULT_TIMEOUT,
        custom_headers: Mapping[str, str] | None = None,
        custom_query: Mapping[str, object] | None = None,
    ) -> None:
        self._version = version
        self._base_url = self._enforce_trailing_slash(normalize_httpx_url(base_url))
        self.max_retries = max_retries
        self.timeout = timeout
        self._custom_headers = custom_headers or {}
        self._custom_query = custom_query or {}
        self._strict_response_validation = _strict_response_validation
        self._idempotency_header = None
        self._platform: Platform | None = None

        if max_retries is None:  # pyright: ignore[reportUnnecessaryComparison]
            raise TypeError(
                "max_retries cannot be None. If you want to disable retries, pass `0`; if you want unlimited retries, pass `math.inf` or a very high number; if you want the default behavior, pass `openai.DEFAULT_MAX_RETRIES`"
            )

    def _enforce_trailing_slash(self, url: URL) -> URL:
        if url.raw_path.endswith(b"/"):
            return url
        return url.copy_with(raw_path=url.raw_path + b"/")

    def _make_status_error_from_response(
        self,
        response: httpx2.Response,
    ) -> APIStatusError:
        if response.is_closed and not response.is_stream_consumed:
            # We can't read the response body as it has been closed
            # before it was read. This can happen if an event hook
            # raises a status error.
            body = None
            err_msg = f"Error code: {response.status_code}"

View on GitHub (pinned to 9917c6e28e)

Solutions

Ensure the vector store exists first: store = await client.vector_stores.create(name=...), then pass store.id.
Check that earlier steps in your async pipeline succeeded before creating file batches; don't swallow exceptions from store creation.
Validate the ID variable is a non-empty string before the call.

Example fix

# before
batch = await client.vector_stores.file_batches.create(vector_store_id=store_id, file_ids=[file.id])  # store_id is None

# after
store = await client.vector_stores.create(name="docs")
batch = await client.vector_stores.file_batches.create(vector_store_id=store.id, file_ids=[file.id])

Defensive patterns

Strategy: validation

Validate before calling

if not vector_store_id:
    raise ValueError("vector_store_id is required; create the store first")
batch = await client.vector_stores.file_batches.create(vector_store_id=vector_store_id, file_ids=file_ids)

Type guard

def is_valid_vector_store_id(v: object) -> bool:
    return isinstance(v, str) and v.startswith("vs_") and len(v) > 3

Prevention

Await and extract .id from store creation before creating batches.
Fail the whole pipeline when the store-creation step errors; do not continue.

When it happens

Trigger: Awaiting create(vector_store_id='') or vector_store_id=None on AsyncVectorStoreFileBatches, commonly when the store was supposed to be created earlier but that step failed or was skipped.

Common situations: Chained async flows where the store creation result was not awaited or its ID not extracted, env-based store IDs that are unset, or error paths that continue to the batch step after a failed store creation.

Related errors

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