openai/openai-python · error · TypeError

Pagination is only supported with mappings

Error message

Pagination is only supported with mappings

What it means

The OpenAI Python SDK raises this ValueError when client.vector_stores.file_batches.cancel() (sync) is called with a falsy vector_store_id (empty string, None). It is a client-side guard added before the HTTP request so an invalid path parameter fails fast instead of producing a malformed URL or a confusing 404 from the API.

Source

Thrown at src/openai/_base_client.py:236

    def _info_to_options(self, info: PageInfo) -> FinalRequestOptions:
        options = model_copy(self._options)
        options._strip_raw_response_header()

        if not isinstance(info.params, NotGiven):
            options.params = {**options.params, **info.params}
            return options

        if not isinstance(info.url, NotGiven):
            params = self._params_from_url(info.url)
            url = info.url.copy_with(params=params)
            options.params = dict(url.params)
            options.url = str(url)
            return options

        if not isinstance(info.json, NotGiven):
            if not is_mapping(info.json):
                raise TypeError("Pagination is only supported with mappings")

            if not options.json_data:
                options.json_data = {**info.json}
            else:
                if not is_mapping(options.json_data):
                    raise TypeError("Pagination is only supported with mappings")

                options.json_data = {**options.json_data, **info.json}
            return options

        raise ValueError("Unexpected PageInfo state")


class BaseSyncPage(BasePage[_T], Generic[_T]):
    _client: SyncAPIClient = pydantic.PrivateAttr()

    def _set_private_attributes(
        self,

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Check the variable holding vector_store_id right before the call; assign the real 'vs_...' ID from the vector store you created or retrieved.
2. If the ID comes from environment/config, verify it is set (os.environ.get('VECTOR_STORE_ID')) and fail loudly at startup if missing.
3. Confirm you are using the IDs in the right order: cancel(vector_store_id='vs_...', batch_id='vsfb_...').
4. If constructing IDs dynamically, log or assert they are non-empty strings before invoking the SDK.

Example fix

// before
batch = client.vector_stores.file_batches.cancel(vector_store_id=store_id, batch_id=batch_id)  # store_id == ''

# after
if not store_id:
    raise ValueError("vector_store_id is missing; create or retrieve the vector store first")
batch = client.vector_stores.file_batches.cancel(vector_store_id=store_id, batch_id=batch_id)

if not isinstance(vector_store_id, str) or not vector_store_id.strip():
    raise ValueError("vector_store_id must be a non-empty string")
client.vector_stores.file_batches.cancel(vector_store_id=vector_store_id, batch_id=batch_id)

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

When it happens

Trigger: Calling cancel(vector_store_id='', batch_id='vsfb_...') or passing a variable that was never assigned (defaults to '' or None) on the synchronous VectorStoreFileBatches resource.

Common situations: Loading IDs from config/env vars that are unset, using a store ID from a deleted vector store, refactoring that dropped the variable assignment, or passing a create() response field name incorrectly (e.g. mistaking file_batch.id for vector_store.id).

Related errors

• No next page expected; please check `.has_next_page()` befor
• max_retries cannot be None. If you want to disable retries,
• Unexpected JSON data type, {type(json_data)}, cannot merge w
• Expected query input to be a dictionary for multipart reques
• Passing both `content` and `json_data` is not supported

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