●Change8

Migrating to Pinecone Client v9.1.0

Version v9.1.0 introduces 2 breaking changes. This guide details how to update your code.

Released: 6/4/2026

2
Breaking Changes
3
Migration Steps
16
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

RetryConfig.max_retriesRetryConfig.backoff_factorpinecone.errors.RateLimitErrorIndex.searchAsyncIndex.searchGrpcIndex.searchGrpcIndexAsyncIndex.query_namespacesGrpcIndex.query_namespacesGrpcIndex.query_namespaces_asyncGrpcIndex.fetch_by_metadataGrpcIndex.start_importGrpcIndex.describe_importGrpcIndex.cancel_importGrpcIndex.list_importsGrpcIndex.list_imports_paginated

Breaking Changes

●Issue #1

The behavior of `RetryConfig.max_retries` on the REST transport has changed to match gRPC: it now counts retries only (N retries after the initial attempt, up to N+1 total requests), instead of counting total attempts. If you explicitly set `max_retries`, you may need to increase its value by 1 to maintain the same number of total requests.

●Issue #2

The default value for `RetryConfig.backoff_factor` has changed from `2.0` to `0.25`. This factor is now interpreted as the minimum delay floor in the decorrelated-jitter formula, resulting in shorter initial waits. Callers relying on the old default should re-evaluate their desired wait times; a v8 `backoff_factor=2.0` roughly maps to a new value of `0.5` for a comparable first-retry delay.

Migration Steps

  1. 1
    If you explicitly configured `RetryConfig.max_retries`, consider increasing the value by 1 for REST transports to maintain the same number of total attempts.
  2. 2
    If you explicitly configured `RetryConfig.backoff_factor`, re-read its documentation as its meaning has changed from an exponential multiplier to a minimum delay floor in the jitter calculation. Adjust the value based on desired initial wait times.
  3. 3
    Update code that catches throttling errors to use the new `pinecone.errors.RateLimitError` for specific handling of HTTP 429s.

Release Summary

This release focuses on retry resilience, introducing decorrelated jitter and automatic concurrency back-off under throttling, alongside a new dedicated `RateLimitError`. It also brings `GrpcIndex` to feature parity with REST clients and restores compatibility for v8 search query syntax.

Need More Details?

View the full release notes and all changes for Pinecone Client v9.1.0.

View Full Changelog