What causes "{name} must not be empty." in deepset-ai/haystack?

Provide a non-empty embedding, e.g. `embedding=[0.1, 0.2, 0.3]`

{name} must not be empty.

Error message

{name} must not be empty.

What it means

`_coerce_embedding` rejects empty sequences: an embedding with zero components is meaningless and would break downstream vector comparisons, so passing `embedding=[]` (or an `embedding_fn` returning `[]`) raises this ValueError. The `name` placeholder identifies which argument was empty.

Source

Thrown at haystack/components/embedders/mock_utils.py:52

    """
    digest = hashlib.sha256(text.encode("utf-8")).digest()
    seed = int.from_bytes(digest[:8], "big")
    rng = random.Random(seed)
    vector = [rng.uniform(-1.0, 1.0) for _ in range(dimension)]
    return _l2_normalize(vector)


def _coerce_embedding(value: object, *, name: str) -> list[float]:
    """
    Validate that `value` is a non-empty sequence of numbers and coerce it into a list of floats.

    :param value: The value to validate, e.g. a user-provided fixed embedding or the output of an `embedding_fn`.
    :param name: How to refer to `value` in error messages, e.g. ``"'embedding'"``.
    """
    if not isinstance(value, (list, tuple)) or not all(isinstance(item, (int, float)) for item in value):
        raise TypeError(f"{name} must be a sequence of numbers, got {type(value)}.")
    if len(value) == 0:
        raise ValueError(f"{name} must not be empty.")
    return [float(item) for item in value]


def _estimate_usage(texts: list[str]) -> dict[str, int]:
    """
    Roughly estimate token usage as whitespace-separated word counts.

    This is an approximation (not real tokenization) intended to give downstream code realistic-looking metadata.
    """
    prompt_tokens = sum(len(text.split()) for text in texts)
    return {"prompt_tokens": prompt_tokens, "total_tokens": prompt_tokens}

View on GitHub (pinned to e318778c9b)

Solutions

Provide a non-empty embedding, e.g. `embedding=[0.1, 0.2, 0.3]`
If the vector is computed, guard with a length check and raise/default before constructing
Ensure `embedding_fn` always returns at least one number

Example fix

// before
parts = value.split(",")
MockTextEmbedder(embedding=[float(p) for p in parts])  # crashes when value == ""
// after
embedding = [float(p) for p in value.split(",")] if value else [0.0]
MockTextEmbedder(embedding=embedding)

Defensive patterns

Strategy: validation

Validate before calling

if not embedding:
    embedding = [0.0]
embedder = MockDocumentEmbedder(embedding=embedding)

Type guard

def is_non_empty_embedding(value) -> bool:
    return isinstance(value, (list, tuple)) and len(value) > 0

Try / catch

try:
    embedder = MockDocumentEmbedder(embedding=embedding)
except ValueError:
    embedder = MockDocumentEmbedder(embedding=[0.0] * fallback_dimension)

Prevention

Check for empty lists before passing computed embeddings
Give embedding_fn a guaranteed non-empty return path
Fix fixtures that parse empty strings into empty embedding lists

When it happens

Trigger: `MockTextEmbedder(embedding=[])`, `MockDocumentEmbedder(embedding=())`, or `embedding_fn=lambda t: []` returning an empty list at embed time.

Common situations: Building the embedding from an empty collection (e.g. splitting an empty string); a config file with `"embedding": []`; a fixture that filters out all values; an embedding_fn hitting an empty branch.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/633efaf29a962b86. Report an issue: GitHub.