# Troubleshooting

## `ValueError: TLS is required for non-loopback targets`

Reason:

- SDK blocks plaintext transport to non-loopback addresses by default.

Fix:

- Provide `TLSConfig(...)` when connecting to remote targets.

## `ValueError: private_key and certificate_chain must be provided together`

Reason:

- mTLS requires both client private key and certificate chain.

Fix:

- Pass both fields in `TLSConfig`, or neither.

## Calls hanging longer than expected

Reason:

- `timeout_s=None` disables request deadlines intentionally.

Fix:

- Omit `timeout_s` to use default timeout (`30s`), or set explicit `timeout_s>0`.

## Authentication failures after key rotation

Reason:

- Dynamic key provider may return stale/invalid values.

Fix:

- Verify provider output is non-empty and free of control characters.
- Use `set_api_key(...)` for deterministic key swaps if provider logic is unnecessary.

## `WaitForReady` timeout

Reason:

- Server is unreachable, still starting, or blocked by network/firewall.

Fix:

- Check target reachability.
- Validate server logs.
- Increase `wait_for_ready(timeout_s=...)` for cold starts.

## `CircuitOpenError` on read calls

Reason:

- Circuit breaker is open after consecutive transient failures.

Fix:

- Validate server availability and retry once recovery timeout elapses.
- Tune `CircuitBreakerPolicy` thresholds/timeouts if fail-fast is too aggressive.

## Bulk delete/query request too large

Reason:

- gRPC message may exceed configured limits.

Fix:

- Reduce batch size or increase message limit via `channel_options`.
