agentscope-ai/agentscope · error · ValueError

DimensionPolicy: kind=ANY requires dimension=None, got dimen

Error message

DimensionPolicy: kind=ANY requires dimension=None, got dimension={self.dimension!r}.

What it means

DimensionPolicy enforces an invariant in _enforce_kind_dimension_invariant: when kind is ANY (accept any embedding dimension), the policy must not carry a dimension — a stray value would be silently ignored otherwise, masking a config mistake. ANY + dimension set raises this ValueError. (Duplicate of error 158: the message spans two adjacent string literals; both trace the same raise.)

Source

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

        description=(
            "The required dimension when ``kind`` is ``FIXED`` or "
            "``LOCKED_BY_EXISTING``.  Always ``None`` for ``ANY``."
        ),
    )
    """The required dimension, or ``None`` when any dimension is fine."""

    @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.

View on GitHub (pinned to e90f1c7592)

Solutions

1. Set dimension=None (or omit the field) when kind is ANY
2. When flipping kind to ANY in stored config, strip/null the dimension key in the same change
3. Validate policy config at load time: if kind=='any', pop the dimension before constructing
4. If you actually need to pin a dimension, use FIXED/RANGE kinds, which require it

Example fix

# before
policy = DimensionPolicy(kind=DimensionPolicyKind.ANY, dimension=1536)  # ValueError

# after
policy = DimensionPolicy(kind=DimensionPolicyKind.ANY, dimension=None)

cfg = {'kind': 'any', 'dimension': 1536}
if cfg.get('kind') == 'any':
    cfg['dimension'] = None
policy = DimensionPolicy(**cfg)

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

try:
    policy = DimensionPolicy(**cfg)
except ValueError:
    if cfg['kind'] == 'any':
        cfg['dimension'] = None
        policy = DimensionPolicy(**cfg)
    else:
        raise

When it happens

Trigger: Constructing DimensionPolicy(kind=DimensionPolicyKind.ANY, dimension=1536) or deserializing a policy dict where kind='any' but a leftover dimension field survives (e.g. config flipped from FIXED to ANY without clearing dimension).

Common situations: Editing policy config from a fixed-dimension setup to 'any' without deleting the dimension key; JSON/YAML defaults injecting dimension; form UIs that always submit the dimension field; LLM-generated config files keeping both fields.

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={self.kind.value} requires a positive
• 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/8c8331527b91128e. Report an issue: GitHub.