cocoindex-io/cocoindex · error · RuntimeError

Embedding dimension is unknown for model

Error message

Embedding dimension is unknown for model {self._model_name_or_path}.

What it means

Raised by the `dimension` property of a sentence-transformers embedding function when the loaded model reports `None` from `get_sentence_embedding_dimension()`. The library needs a concrete integer dimension (e.g. for schema/index setup) and cannot proceed when the model cannot report one.

Solutions

Use a model that is actually a sentence-transformers model (has modules.json / sentence-transformers config), or wrap a plain transformer with sentence_transformers itself.
Load the model and call `model.get_sentence_embedding_dimension()` directly to confirm whether the backend can report a dimension.
If the model is local, verify the download is complete and config files (modules.json, config_sentence_transformers.json) are present.
Pick a known embedding model with a declared dimension (e.g. all-MiniLM-L6-v2) if the current model fundamentally has none.

Example fix

// before
emb = SentenceTransformerEmbedding(model="openai/clip-vit-base-patch32")
print(emb.dimension)  # RuntimeError
// after
emb = SentenceTransformerEmbedding(model="sentence-transformers/all-MiniLM-L6-v2")
print(emb.dimension)  # 384

Defensive patterns

Strategy: validation

Validate before calling

from sentence_transformers import SentenceTransformer
m = SentenceTransformer(model_name)
assert m.get_sentence_embedding_dimension() is not None, f"{model_name} has no declared embedding dimension"

Try / catch

try:
    dim = emb.dimension
except RuntimeError as e:
    if 'Embedding dimension is unknown' in str(e):
        emb = SentenceTransformerEmbedding(model=FALLBACK_MODEL)
        dim = emb.dimension
    else:
        raise

Prevention

Only use models from the sentence-transformers ecosystem (with modules.json) for this op.
Probe `get_sentence_embedding_dimension()` on any new model before registering it.
Verify local model directories are fully downloaded (config + modules.json present).

When it happens

Trigger: Accessing `.dimension` on a SentenceTransformerEmbedding wrapper for a model whose sentence-transformers backend cannot determine an embedding dimension — typically models loaded without a sentence-transformers pooling/ sentence embedding head.

Common situations: Pointing the op at a raw HF model (e.g. a bare transformer or a CLIP-style model) that is not a sentence-transformers model; loading a local path with missing config files; model files for a repo that doesn't declare dimension in its configuration.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/67ae3de6995e461f. Report an issue: GitHub.

Appendix: source

Thrown at python/cocoindex/ops/sentence_transformers.py:218

            RuntimeError: If the model's embedding dimension cannot be determined.
        """
        dim = await self.dimension()
        return _schema.VectorSchema(dtype=_np.dtype(_np.float32), size=dim)

    @coco.fn.as_async(runner=coco.GPU, memo=True)
    def dimension(self) -> int:
        """Return the embedding dimension for this model.

        Returns:
            The embedding dimension as an integer.

        Raises:
            RuntimeError: If the model's embedding dimension cannot be determined.
        """
        model = self._get_model()
        dim = model.get_sentence_embedding_dimension()
        if dim is None:
            raise RuntimeError(
                f"Embedding dimension is unknown for model {self._model_name_or_path}."
            )
        return int(dim)

    def __coco_memo_key__(self) -> object:
        return (self._model_name_or_path, self._device, self._trust_remote_code)

View on GitHub (pinned to e84aa99b32)