{"record":{"id":"2daf6bea7112b59d","repo":"agentscope-ai/agentscope","slug":"dimensionpolicy-kind-self-kind-value-requires-a","errorCode":null,"errorMessage":"DimensionPolicy: kind={self.kind.value} requires a positive dimension, got dimension={self.dimension!r}.","messagePattern":"DimensionPolicy: kind=(.+?) requires a positive dimension, got dimension=(.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/app/rag/knowledge_base_manager/_dimension_policy.py","lineNumber":91,"sourceCode":"\n    @model_validator(mode=\"after\")\n    def _enforce_kind_dimension_invariant(self) -> \"DimensionPolicy\":\n        \"\"\"Reject states like ``ANY + dimension=768`` or ``FIXED + None``.\n\n        Without this guard, downstream code silently produces wrong\n        results (``ANY`` ignores a stray dimension) or crashes\n        (``FIXED`` with ``None`` makes ``filter_card`` raise\n        ``TypeError`` on ``target not in card.supported_dimensions``).\n        \"\"\"\n        if self.kind is DimensionPolicyKind.ANY:\n            if self.dimension is not None:\n                raise ValueError(\n                    \"DimensionPolicy: kind=ANY requires dimension=None, \"\n                    f\"got dimension={self.dimension!r}.\",\n                )\n        else:\n            if self.dimension is None or self.dimension <= 0:\n                raise ValueError(\n                    f\"DimensionPolicy: kind={self.kind.value} requires a \"\n                    f\"positive dimension, got dimension={self.dimension!r}.\",\n                )\n        return self\n\n    def accepts(self, dimensions: int) -> bool:\n        \"\"\"Check whether a candidate dimension satisfies this policy.\n\n        Args:\n            dimensions (`int`):\n                The candidate output dimension.\n\n        Returns:\n            `bool`:\n                ``True`` if the dimension is acceptable.\n        \"\"\"\n        if self.kind is DimensionPolicyKind.ANY:\n            return dimensions > 0","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/app/rag/knowledge_base_manager/_dimension_policy.py#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set a positive int matching your embedding model, e.g. DimensionPolicy(kind=FIXED, dimension=1536)","Populate dimension from the actual embedding model spec rather than hardcoding env vars","Validate loaded config: require dimension > 0 unless kind is ANY","If unsure of the dimension, use kind=ANY with dimension=None"],"exampleFix":"# before\npolicy = DimensionPolicy(kind=DimensionPolicyKind.FIXED, dimension=None)  # ValueError\n\n# after\npolicy = DimensionPolicy(kind=DimensionPolicyKind.FIXED, dimension=1536)","handlingStrategy":"validation","validationCode":"DIM = int(os.environ.get('EMBED_DIM', '1536'))\nassert DIM > 0, 'EMBED_DIM must be a positive integer'\npolicy = DimensionPolicy(kind=DimensionPolicyKind.FIXED, dimension=DIM)","typeGuard":"def has_positive_dimension(cfg: dict) -> bool:\n    dim = cfg.get('dimension')\n    return str(cfg.get('kind', '')).lower() == 'any' or (isinstance(dim, int) and dim > 0)","tryCatchPattern":"try:\n    policy = DimensionPolicy(**cfg)\nexcept ValueError as e:\n    if 'requires a positive dimension' in str(e):\n        raise ValueError('Set the embedding dimension (e.g. 1536) or use kind=ANY') from e\n    raise","preventionTips":["Derive dimension from the embedding model's spec, not hardcoded guesses","Guard env-var parsing: unset strings must not become None/0 dimensions","If the dimension is unknown up front, use kind=ANY with dimension=None"],"tags":["rag","validation","embedding-dimension","config"],"backgroundTag":"config-validation-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}