agentscope-ai/agentscope · error · ValueError

dimensions is required: pass it explicitly to EmbeddingModel

Error message

dimensions is required: pass it explicitly to EmbeddingModelBase.__init__ or include it in the legacy `parameters` mapping.

What it means

EmbeddingModelBase requires the embedding dimensionality to be known: it must be passed as the explicit dimensions constructor argument or included in the legacy `parameters` mapping. If neither is present, init fails immediately because dimensions drive cache sizing and downstream vector-store schemas.

Source

Thrown at src/agentscope/embedding/_embedding_base.py:158

            max_retries (`int`):
                The maximum number of retries for each batch API call.
                Only exceptions listed in
                :meth:`_get_retryable_exceptions` count against this
                budget.
            retry_delay (`float`):
                Seconds to sleep between retry attempts.
        """
        resolved_parameters = parameters or self.Parameters()
        # Backward-compat: older session/KB configs persisted
        # ``dimensions`` inside ``parameters``.  Promote it to the
        # constructor argument when the caller did not pass one
        # explicitly, then strip it from the parameters object so it
        # never reaches provider-specific request payloads.
        param_dump = resolved_parameters.model_dump()
        legacy_dimensions = param_dump.pop("dimensions", None)
        if dimensions is None:
            if legacy_dimensions is None:
                raise ValueError(
                    "dimensions is required: pass it explicitly to "
                    "EmbeddingModelBase.__init__ or include it in the "
                    "legacy `parameters` mapping.",
                )
            dimensions = int(legacy_dimensions)
            resolved_parameters = type(resolved_parameters)(**param_dump)
        elif legacy_dimensions is not None:
            # Both routes set it — explicit constructor wins, strip the
            # legacy mirror so it can't drift.
            resolved_parameters = type(resolved_parameters)(**param_dump)

        if dimensions <= 0:
            raise ValueError(
                f"dimensions must be a positive integer, got {dimensions}.",
            )

        self.credential = credential
        self.model = model

View on GitHub (pinned to e90f1c7592)

Solutions

1. Pass dimensions=1024 (or the model's true dimensionality) to the constructor
2. Or include dimensions in the legacy parameters mapping if you use that route
3. Check the provider's docs for the exact dimension count of your chosen model

Example fix

# before
model = MyDashScopeEmbedding(model="text-embedding-v3", credential=cred)
# after
model = MyDashScopeEmbedding(model="text-embedding-v3", credential=cred, dimensions=1024)

if dimensions is None:\n    dimensions = DEFAULT_DIMS[model_name]  # e.g. 1024
model = Emb(model=model_name, dimensions=dimensions, ...)

When it happens

Trigger: Constructing an embedding model subclass without dimensions=... and without a parameters object containing a dimensions field.

Common situations: Upgrading from an older API where dimensions lived in provider parameters or were inferred; writing model configs by hand and omitting the field; loading cards whose YAML lacks dimensions.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• basedir must not be empty.
• dimensions must be a positive integer, got {dimensions}.
• "AgentScopeEmbedding requires `model` in the config to be an
• The injection template must contain the '{runtime_state}' pl
• MCP {card.name!r} produced an invalid client: {e}

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/dd874b0166c8b48b. Report an issue: GitHub.