deepset-ai/haystack · error

'dimension' must be a positive integer.

Error message

'dimension' must be a positive integer.

What it means

MockDocumentEmbedder validates that `dimension` is a positive integer because generated embeddings must have at least one component. A dimension of zero or negative is nonsensical, so the constructor raises this ValueError immediately rather than producing broken embeddings later.

Source

Thrown at haystack/components/embedders/mock_document_embedder.py:91

            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 each text before embedding.
        :param suffix: A string to add at the end of each text before embedding.
        :param meta_fields_to_embed: List of metadata fields to embed along with the document text.
        :param embedding_separator: Separator used to concatenate the metadata fields to the document text.
        :param progress_bar: Accepted for interface compatibility with real Document Embedders and ignored.
        :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.meta_fields_to_embed = meta_fields_to_embed or []
        self.embedding_separator = embedding_separator
        self.progress_bar = progress_bar
        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,

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass a positive integer, e.g. `dimension=768`
2. If the dimension comes from config, validate/default it before constructing: `dimension = configured or 768`
3. Check upstream variables that compute the dimension for off-by-one or empty-input bugs

Example fix

// before
MockDocumentEmbedder(dimension=len(configured_embeddings) - 1)
// after
MockDocumentEmbedder(dimension=max(1, len(configured_embeddings)))

dimension = int(dimension)
if dimension <= 0:
    dimension = 768
embedder = MockDocumentEmbedder(dimension=dimension)

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

try:
    embedder = MockDocumentEmbedder(dimension=dimension)
except ValueError:
    embedder = MockDocumentEmbedder(dimension=768)

When it happens

Trigger: `MockDocumentEmbedder(dimension=0)` or `MockDocumentEmbedder(dimension=-8)` (also non-integer numerics like 0.0 that satisfy `<= 0`).

Common situations: Computing the dimension from a variable that defaults to 0 or from an empty collection; typos like `dim=-1` intending 'auto'; reading dimension from config where the key is missing/zero.

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/6ec7c84ec90fa7d7. Report an issue: GitHub.