agentscope-ai/agentscope · error · ValueError

DimensionPolicy: kind={self.kind.value} requires a positive

Error message

DimensionPolicy: kind={self.kind.value} requires a positive dimension, got dimension={self.dimension!r}.

What it means

The FIXED (non-ANY) branch of the DimensionPolicy invariant: policies that pin or bound a dimension require a positive integer. dimension=None or dimension<=0 raises ValueError, because downstream filter_card would otherwise crash with TypeError ('None not in supported_dimensions') or accept nonsense values.

Source

Thrown at src/agentscope/app/rag/knowledge_base_manager/_dimension_policy.py:91

    @model_validator(mode="after")
    def _enforce_kind_dimension_invariant(self) -> "DimensionPolicy":
        """Reject states like ``ANY + dimension=768`` or ``FIXED + None``.

        Without this guard, downstream code silently produces wrong
        results (``ANY`` ignores a stray dimension) or crashes
        (``FIXED`` with ``None`` makes ``filter_card`` raise
        ``TypeError`` on ``target not in card.supported_dimensions``).
        """
        if self.kind is DimensionPolicyKind.ANY:
            if self.dimension is not None:
                raise ValueError(
                    "DimensionPolicy: kind=ANY requires dimension=None, "
                    f"got dimension={self.dimension!r}.",
                )
        else:
            if self.dimension is None or self.dimension <= 0:
                raise ValueError(
                    f"DimensionPolicy: kind={self.kind.value} requires a "
                    f"positive dimension, got dimension={self.dimension!r}.",
                )
        return self

    def accepts(self, dimensions: int) -> bool:
        """Check whether a candidate dimension satisfies this policy.

        Args:
            dimensions (`int`):
                The candidate output dimension.

        Returns:
            `bool`:
                ``True`` if the dimension is acceptable.
        """
        if self.kind is DimensionPolicyKind.ANY:
            return dimensions > 0

View on GitHub (pinned to e90f1c7592)

Solutions

1. Set a positive int matching your embedding model, e.g. DimensionPolicy(kind=FIXED, dimension=1536)
2. Populate dimension from the actual embedding model spec rather than hardcoding env vars
3. Validate loaded config: require dimension > 0 unless kind is ANY
4. If unsure of the dimension, use kind=ANY with dimension=None

Example fix

# before
policy = DimensionPolicy(kind=DimensionPolicyKind.FIXED, dimension=None)  # ValueError

# after
policy = DimensionPolicy(kind=DimensionPolicyKind.FIXED, dimension=1536)

DIM = int(os.environ.get('EMBED_DIM', '1536'))
assert DIM > 0, 'EMBED_DIM must be a positive integer'
policy = DimensionPolicy(kind=DimensionPolicyKind.FIXED, dimension=DIM)

def has_positive_dimension(cfg: dict) -> bool:
    dim = cfg.get('dimension')
    return str(cfg.get('kind', '')).lower() == 'any' or (isinstance(dim, int) and dim > 0)

try:
    policy = DimensionPolicy(**cfg)
except ValueError as e:
    if 'requires a positive dimension' in str(e):
        raise ValueError('Set the embedding dimension (e.g. 1536) or use kind=ANY') from e
    raise

When it happens

Trigger: DimensionPolicy(kind=DimensionPolicyKind.FIXED, dimension=None) or dimension=0/-1; also deserialized policy dicts missing the dimension key or with 0 defaults under a non-ANY kind.

Common situations: Config where dimension is expected from an env var that is unset (parses to None/0); optional-field defaults serializing to None; switching kind from ANY to FIXED without adding a dimension; upstream embedding-model change (e.g. 1536 → 3072) handled by zeroing the field temporarily.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• DimensionPolicy: kind=ANY requires dimension=None, got dimen
• overlap must be less than chunk_size, got overlap={self.over
• The injection template must contain the '{runtime_state}' pl
• MCP {card.name!r} produced an invalid client: {e}
• "build_mem0_config requires `chat_model` and `embedding_mode

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