chroma-core/chroma · error · ValueError

Preferred providers must be a list of strings

Error message

Preferred providers must be a list of strings

What it means

ONNXMiniLM_L6_V2.__init__ validates the optional preferred_providers argument: if it is non-empty and any element fails isinstance(i, str), it raises ValueError("Preferred providers must be a list of strings"). Providers are ONNX Runtime execution-provider names (e.g. "CPUExecutionProvider", "CUDAExecutionProvider") passed straight into an InferenceSession later, so non-string entries indicate a malformed config.

Source

Thrown at chromadb/utils/embedding_functions/onnx_mini_lm_l6_v2.py:59

    ARCHIVE_FILENAME = "onnx.tar.gz"
    MODEL_DOWNLOAD_URL = (
        "https://chroma-onnx-models.s3.amazonaws.com/all-MiniLM-L6-v2/onnx.tar.gz"
    )
    _MODEL_SHA256 = "913d7300ceae3b2dbc2c50d1de4baacab4be7b9380491c27fab7418616a16ec3"

    def __init__(self, preferred_providers: Optional[List[str]] = None) -> None:
        """
        Initialize the ONNXMiniLM_L6_V2 embedding function.

        Args:
            preferred_providers (List[str], optional): The preferred ONNX runtime providers.
                Defaults to None.
        """
        # convert the list to set for unique values
        if preferred_providers and not all(
            [isinstance(i, str) for i in preferred_providers]
        ):
            raise ValueError("Preferred providers must be a list of strings")
        # check for duplicate providers
        if preferred_providers and len(preferred_providers) != len(
            set(preferred_providers)
        ):
            raise ValueError("Preferred providers must be unique")

        self._preferred_providers = preferred_providers

        try:
            # Equivalent to import onnxruntime
            self.ort = importlib.import_module("onnxruntime")
        except ImportError:
            raise ValueError(
                "The onnxruntime python package is not installed. Please install it with `pip install onnxruntime`"
            )
        try:
            # Equivalent to from tokenizers import Tokenizer
            self.Tokenizer = importlib.import_module("tokenizers").Tokenizer

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Pass a flat list of provider-name strings: ["CUDAExecutionProvider", "CPUExecutionProvider"]
2. Coerce before constructing: providers = [str(p) for p in providers if p is not None]
3. If config comes from an enum, map it to its name: [p.name for p in provider_enums]

Example fix

// before
fn = ONNXMiniLM_L6_V2(preferred_providers=["CUDAExecutionProvider", 1])  # ValueError

// after
fn = ONNXMiniLM_L6_V2(preferred_providers=["CUDAExecutionProvider", "CPUExecutionProvider"])

def validate_providers(providers):
    if providers is None:
        return None
    if not all(isinstance(p, str) for p in providers):
        providers = [str(p) for p in providers if p is not None]
    return list(providers)
fn = ONNXMiniLM_L6_V2(preferred_providers=validate_providers(cfg.get("providers")))

def is_provider_list(p) -> bool:
    """True when p is None or a non-empty flat list of provider-name strings."""
    return p is None or (isinstance(p, list) and len(p) > 0 and all(isinstance(i, str) for i in p))

When it happens

Trigger: ONNXMiniLM_L6_V2(preferred_providers=["CUDAExecutionProvider", 0]) or [None] or [b"CPUExecutionProvider"]; building the list dynamically from config that contains ints/enums (e.g. an OrtProvider enum not converted to .name); passing a nested list like [["CUDAExecutionProvider"]] instead of a flat one.

Common situations: Loading preferred_providers from YAML/JSON where an entry parsed as a number or null; porting code from onnxruntime Python API examples that use enum objects; copy-pasting provider dicts ({"CUDAExecutionProvider": {...}}) where a plain string list is expected.

Related errors

• Preferred providers must be subset of available providers: {
• Preferred providers must be unique
• Could not build embedding function {ef_config['name']} from
• Updating '{key}' is not supported for {NAME}
• The onnxruntime python package is not installed. Please inst

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/c93206d6b143d8ab. Report an issue: GitHub.