fix: raise provider-specific errors from vectorizer _set_model_dims()

[Aryan-Pardeshi]

Fixes #485

Every vectorizer probes its provider with a throwaway embedding call to learn the model's dimensionality. When that probe failed, all eight raised the same message under a # fall back (TODO get more specific) comment:

Error setting embedding model dimensions: <whatever the SDK said>

That tells the caller nothing about which provider rejected them or what to change, which is exactly the troubleshooting cost the issue describes.

Each _set_model_dims() now catches the exception classes its SDK actually raises and reports the provider, the model, and a concrete next step:

• text/openai.py, text/azureopenai.py — AuthenticationError, PermissionDeniedError, NotFoundError, APIConnectionError. The Azure messages talk about deployments rather than models, since Azure addresses models by deployment name and a wrong deployment is the common failure.
• text/cohere.py — UnauthorizedError, NotFoundError, then cohere.core.api_error.ApiError.
• text/mistral.py — mistralai.models.SDKError.
• voyageai.py — AuthenticationError, InvalidRequestError, APIConnectionError from voyageai.error.
• bedrock.py — ClientError, split on the error code so credential problems and unknown model ids give different advice, then BotoCoreError.
• vertexai.py — PermissionDenied, Unauthenticated, NotFound, then GoogleAPICallError.
• text/huggingface.py — OSError for a model that will not load, RuntimeError for the CUDA OOM/device-mismatch case.

Every class name was verified by importing the installed SDK rather than taken from documentation, since a catch for a class that does not exist is dead code.

Two deliberate choices:

The broad except Exception stays as a final clause in all eight. Narrowing to provider classes alone would let anything unanticipated escape raw instead of surfacing as a ValueError, which would be a regression rather than a fix. The generic clause now also names the provider and model.

Imports are local to the method, matching how these modules already treat their optional SDK dependencies. The SDK is guaranteed importable at that point because __init__ initialises the client before calling _set_model_dims().

tests/unit/test_vectorizer_dim_errors.py drives OpenAI, Azure OpenAI, Bedrock and HuggingFace through their real __init__ with the network client stubbed, so it exercises the same path a user hits with a bad key. It also pins the generic fallback: an unexpected ZeroDivisionError must still arrive as a ValueError.

Verified 7 failed against unmodified main, 7 passed with the change. Full unit suite: 1299 passed, 11 skipped. isort --profile black and black --target-version py311 report no changes.

---

Note

Low Risk
Changes are limited to init-time error wrapping in embedding vectorizers; successful embed paths are unchanged and failures still surface as ValueError.

Overview
When vectorizers fail their startup dimension probe, failures are no longer reported as a generic Error setting embedding model dimensions: … message. OpenAI, Azure OpenAI, Cohere, Mistral, Bedrock, Vertex AI, and VoyageAI now raise a ValueError that names the provider and model/deployment, with the underlying SDK or retry error preserved via raise … from e. The separate KeyError/IndexError branch for “unexpected API response” on that path is removed in favor of the single wrapped handler.

Hugging Face gets the largest behavioral change: SentenceTransformer load failures (OSError, RuntimeError such as CUDA OOM) are caught in _initialize_client with guidance on model path/download and device='cpu', and similar handling is added in _set_model_dims when the probe encode step fails.

tests/unit/test_vectorizer_dim_errors.py locks in model names in messages, exception chaining, HF load errors, VoyageAI’s TypeError path from invalid models, and the generic fallback for unexpected errors.

^{Reviewed by Cursor Bugbot for commit 5a1ebea. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Aryan-Pardeshi]

Good catch, and it went deeper than the first fix. _embed()/_embed_many() already wrap the SDK's own exception in a generic ValueError before _set_model_dims() sees it, so catching the provider exception type directly never fired — confirmed.

There was a second layer underneath that too: _embed/_embed_many are @retry-decorated with retry_if_not_exception_type(TypeError), which does not exempt that ValueError. So a permanent failure like bad credentials gets retried 6 times with exponential backoff before tenacity gives up and raises RetryError, wrapping the ValueError, which wraps the real SDK exception.

_set_model_dims() now unwraps RetryError first, then __cause__/__context__, before dispatching. Tests for OpenAI, Bedrock and HuggingFace now drive the real _embed()/_initialize_client() code (patching only the network client, not _embed itself) so they'd have caught this the first time. HuggingFace also got a real fix for the case you flagged separately — a bad model name now raises where it actually happens, in _initialize_client()'s SentenceTransformer() call, not in _set_model_dims().

Full unit suite: 1303 passed, no regressions.

[Aryan-Pardeshi]

Good catch again — pushed. _embed_many() re-raises InvalidRequestError as TypeError specifically so the retry decorator skips retrying it (a bad model id can't ever succeed). That meant it reached _set_model_dims() as a bare, unwrapped TypeError, never caught by the (ValueError, RetryError) tuple, so it fell to the generic fallback instead of the unrecognized-model message.

Added TypeError to the caught tuple and a test that drives the real _embed_many() code (only the client's .embed() call is stubbed), which fails against the previous except tuple and passes now. Full suite: 1304 passed.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{Reviewed by Cursor Bugbot for commit 098e5e9. Configure here.}

[Aryan-Pardeshi]

Both real, pushed a fix for each.

High: right, cohere.UnauthorizedError/NotFoundError only exist in cohere 5.0+, but the package still declares cohere>=4.44 and the embed path still handles 4.x list responses. Those were referenced unconditionally at import/isinstance time, so any 4.x install would crash on construction. Now using getattr(cohere, "UnauthorizedError", None) etc., and the ApiError import is wrapped in try/except ImportError -- falls through to the generic message on 4.x instead of crashing.

Low: fixed the copy-paste wording, HF's OSError handler now says "failed while determining its dimensions" like the RuntimeError one, since it fires after SentenceTransformer already loaded.

Full suite: 1304 passed, 11 skipped, no regressions.

[vishal-bala]

Hi, thanks for contributing to RedisVL! I appreciate the idea you're going for here, but the current implementation adds a lot of bloated logic and comments for limited lift to an end user. If the goal is to expose the underlying specific error more concretely, I think we can do that by simply chaining the exception into the ValueError

except (...) as ke:
    raise ValueError("...") from ke

That should make it sufficiently visible in the traceback and actionable by others catching this exception, while also maintaining the standard of code quality we expect for this project.

[Aryan-Pardeshi]

@vishal-bala thanks — agreed, and I took the whole thing out rather than trimming it.

5a1ebea collapses every vectorizer's _set_model_dims() to one except Exception as e: raise ValueError(...) from e. The provider-specific handlers, the RetryError.last_attempt.exception() unwrapping and the __cause__/__context__ dispatch are all gone; from e already puts the real SDK error in the traceback, which is what the extra code was reimplementing badly. The message still names the provider and the model so the actionable part survives.

Net diff across the 8 files is +80 / -512.

Verified: black --check and isort --check-only clean on the touched files, mypy reports "Success: no issues found in 7 source files". The rewritten tests/unit/test_vectorizer_dim_errors.py covers OpenAI/Bedrock/HuggingFace end to end against real SDK failures plus a parametrized cause-chaining check for the rest — I ran those standalone rather than through pytest, since tests/conftest.py's session-scoped redis_container fixture needs Docker for even pure unit tests.

The Bugbot comments above all predate this rewrite and point at handlers that no longer exist.