deepset-ai/haystack · error

'dimension' must be a positive integer.

Error message

'dimension' must be a positive integer.

What it means

MockTextEmbedder requires `dimension` to be a positive integer, since every produced embedding must have at least one element. Zero or negative values raise this ValueError in `__init__`.

Source

Thrown at haystack/components/embedders/mock_text_embedder.py:80

        :param embedding: An optional fixed embedding returned for every input. Mutually exclusive with
            `embedding_fn`. If neither is provided, a deterministic embedding is derived from the input text.
        :param embedding_fn: An optional callable that receives the prepared text (after `prefix`/`suffix` are
            applied) and returns the embedding as a list of floats. Mutually exclusive with `embedding`. To support
            serialization, pass a named function (lambdas and nested functions cannot be serialized).
        :param dimension: The number of dimensions of the deterministic embedding. Ignored when `embedding` or
            `embedding_fn` is provided, since their length is determined by the value or callable.
        :param model: The model name reported in the metadata. Purely cosmetic; no model is loaded.
        :param meta: Additional metadata merged into the output `meta`.
        :param prefix: A string to add at the beginning of the text before embedding.
        :param suffix: A string to add at the end of the text before embedding.
        :raises ValueError: If both `embedding` and `embedding_fn` are provided, if `dimension` is not positive, or
            if `embedding` is an empty list.
        :raises TypeError: If `embedding` is not a sequence of numbers.
        """
        if embedding is not None and embedding_fn is not None:
            raise ValueError("Pass either 'embedding' or 'embedding_fn', not both.")
        if dimension <= 0:
            raise ValueError("'dimension' must be a positive integer.")

        self.embedding = _coerce_embedding(embedding, name="'embedding'") if embedding is not None else None
        self.embedding_fn = embedding_fn
        self.dimension = dimension
        self.model = model
        self.meta = meta or {}
        self.prefix = prefix
        self.suffix = suffix
        self._is_warmed_up = False

    def to_dict(self) -> dict[str, Any]:
        """Serialize the component to a dictionary."""
        embedding_fn = serialize_callable(self.embedding_fn) if self.embedding_fn is not None else None
        return default_to_dict(
            self,
            embedding=self.embedding,
            embedding_fn=embedding_fn,
            dimension=self.dimension,

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass a positive integer, e.g. `MockTextEmbedder(dimension=384)`
2. Sanitize the source value: `dimension = value if value and value > 0 else 384`
3. Trace where the dimension is computed and fix the calculation

Example fix

// before
MockTextEmbedder(dimension=len(sizes) - 1)
// after
MockTextEmbedder(dimension=len(sizes) or 384)

if not isinstance(dimension, int) or dimension <= 0:
    dimension = 384
embedder = MockTextEmbedder(dimension=dimension)

def is_valid_dimension(d) -> bool:
    return isinstance(d, int) and d > 0

try:
    embedder = MockTextEmbedder(dimension=dimension)
except ValueError:
    embedder = MockTextEmbedder(dimension=384)

When it happens

Trigger: `MockTextEmbedder(dimension=0)` or `MockTextEmbedder(dimension=-3)`; also computed values like `dimension=len([])` that evaluate to 0.

Common situations: Dimension read from an empty or unset config entry; arithmetic producing 0 (e.g. subtracting from a length); placeholder values left in tests intending to be filled in later.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

• 'dimension' must be a positive integer.
• Pass either 'embedding' or 'embedding_fn', not both.
• Pass either 'embedding' or 'embedding_fn', not both.
• 'response_fn' must return an assistant ChatMessage, got '{re
• Hook of type '{type(h).__name__}' is registered under hook p

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