chroma-core/chroma · error · ValueError

Invalid task: {task}

Error message

Invalid task: {task}

What it means

Thrown by FastembedSparseEmbeddingFunction.embed_query() when query_config was provided but its 'task' value is neither 'document' nor 'query'. The function must map the task to a fastembed SparseTextEmbedding method (model.embed vs model.query_embed); an unknown value, or a missing 'task' key (dict.get returns None), cannot be mapped so the call aborts before any embedding is produced. Only the query path checks query_config; __call__() uses the separately validated self.task.

Source

Thrown at chromadb/utils/embedding_functions/fastembed_sparse_embedding_function.py:129

        try:
            from fastembed import SparseTextEmbedding
        except ImportError:
            raise ValueError(
                "The fastembed python package is not installed. Please install it with `pip install fastembed`"
            )
        model = cast(SparseTextEmbedding, self._model)
        if self.query_config is not None:
            task = self.query_config.get("task")
            if task == "document":
                embeddings = model.embed(
                    list(input),
                )
            elif task == "query":
                embeddings = model.query_embed(
                    list(input),
                )
            else:
                raise ValueError(f"Invalid task: {task}")

            sparse_vectors: SparseVectors = []

            for vec in embeddings:
                sparse_vectors.append(
                    normalize_sparse_vector(
                        indices=vec.indices.tolist(), values=vec.values.tolist()
                    )
                )

            return sparse_vectors

        else:
            return self.__call__(input)

    @staticmethod
    def name() -> str:
        return "fastembed_sparse"

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Set query_config={'task': 'query'} (or 'document') using the exact lowercase literal and the correctly spelled 'task' key
2. Omit query_config entirely if you do not need asymmetric query behavior - embed_query() then falls back to __call__() driven by the constructor's task argument
3. Annotate the dict as FastembedSparseEmbeddingFunctionQueryConfig so a type checker rejects bad keys/values before runtime
4. Log repr(query_config) before calling embed_query to see the exact value that failed

Example fix

# before
ef = FastembedSparseEmbeddingFunction(
    model_name="Qdrant/bm25",
    task="document",
    query_config={"tasks": "query"},  # misspelled key -> task=None -> Invalid task: None
)
ef.embed_query(["what is chroma?"])

# after
from chromadb.utils.embedding_functions.fastembed_sparse_embedding_function import (
    FastembedSparseEmbeddingFunctionQueryConfig,
)
query_config: FastembedSparseEmbeddingFunctionQueryConfig = {"task": "query"}
ef = FastembedSparseEmbeddingFunction(
    model_name="Qdrant/bm25",
    task="document",
    query_config=query_config,
)
ef.embed_query(["what is chroma?"])

from chromadb.utils.embedding_functions import FastembedSparseEmbeddingFunction

VALID_SPARSE_TASKS = {"document", "query"}

def query_config_is_valid(ef: FastembedSparseEmbeddingFunction) -> bool:
    qc = ef.query_config
    return qc is None or qc.get("task") in VALID_SPARSE_TASKS

assert query_config_is_valid(ef), (
    f"query_config.task must be 'document' or 'query', got {ef.query_config!r}"
)

from typing import TypeGuard
from chromadb.utils.embedding_functions.fastembed_sparse_embedding_function import (
    FastembedSparseEmbeddingFunctionQueryConfig,
)

def is_valid_query_config(
    cfg: object,
) -> TypeGuard[FastembedSparseEmbeddingFunctionQueryConfig]:
    return (
        isinstance(cfg, dict)
        and set(cfg) == {"task"}
        and cfg["task"] in ("document", "query")
    )

When it happens

Trigger: Calling ef.embed_query(texts) on an instance built with query_config={'tasks': 'query'} (misspelled key, so task is None), query_config={'task': 'queries'}, {'task': 'QUERY'}, or any value outside the Literal['document','query'] allowed by FastembedSparseEmbeddingFunctionQueryConfig.

Common situations: Typos in the query_config dict key or value; config round-tripped through JSON/YAML that uppercased or renamed 'task'; copying an example config written for a different embedding function; treating the TypedDict task field as free-form text instead of the two allowed literals.

Related errors

• Invalid task: {self.task}
• The fastembed python package is not installed. Please instal
• Keyword argument {key} is not a primitive type
• Invalid task: {self.query_config.get('task')}
• Updating '${key}' is not supported for ${NAME}

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