agentscope-ai/agentscope · error · ValueError

dimensions must be a positive integer, got {dimensions}.

Error message

dimensions must be a positive integer, got {dimensions}.

What it means

EmbeddingModelBase validates that the resolved dimensions value is a positive integer; zero or negative values are rejected at construction time since vector dimensionality must be positive.

Source

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

        # 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
        self.dimensions = dimensions
        self.parameters = resolved_parameters
        self.context_size = context_size
        self.batch_size = batch_size
        self.max_retries = max_retries
        self.retry_delay = retry_delay

    @classmethod
    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
        """Return exception types that should trigger a retry.

        Defaults to an empty tuple (no retries).  Subclasses can
        override to declare provider-specific retryable exceptions.

View on GitHub (pinned to e90f1c7592)

Solutions

1. Set dimensions to the model's actual positive dimension count
2. Guard config-derived values: fall back to a sane default when the computed value is <= 0
3. Fail fast at config load with a clear message

Example fix

# before
dims = cfg.get("dims", 0)
model = Emb(model="v3", dimensions=dims)
# after
dims = cfg.get("dims") or 1024
model = Emb(model="v3", dimensions=dims)

dimensions = dimensions if isinstance(dimensions, int) and dimensions > 0 else DEFAULT_DIMS

def valid_dimensions(d) -> bool:\n    return isinstance(d, int) and not isinstance(d, bool) and d > 0

When it happens

Trigger: Passing dimensions=0 or a negative number explicitly, or a legacy parameters mapping with a non-positive dimensions value.

Common situations: Dimensions computed from config arithmetic that defaults to 0 when unset; typos (e.g. dimensions=-1 as a 'not set' sentinel); copy-paste from examples with placeholder values.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• dimensions is required: pass it explicitly to EmbeddingModel
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• The 'reserve_ratio' of the context config must be smaller th
• The 'context_buffer_ratio' of the injection config must be s
• Input validation failed for tool '{tool_call.name}': {e.mess

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