{"record":{"id":"dd874b0166c8b48b","repo":"agentscope-ai/agentscope","slug":"dimensions-is-required-pass-it-explicitly-to-embe","errorCode":null,"errorMessage":"dimensions is required: pass it explicitly to EmbeddingModelBase.__init__ or include it in the legacy `parameters` mapping.","messagePattern":"dimensions is required: pass it explicitly to EmbeddingModelBase\\.__init__ or include it in the legacy `parameters` mapping\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/embedding/_embedding_base.py","lineNumber":158,"sourceCode":"            max_retries (`int`):\n                The maximum number of retries for each batch API call.\n                Only exceptions listed in\n                :meth:`_get_retryable_exceptions` count against this\n                budget.\n            retry_delay (`float`):\n                Seconds to sleep between retry attempts.\n        \"\"\"\n        resolved_parameters = parameters or self.Parameters()\n        # Backward-compat: older session/KB configs persisted\n        # ``dimensions`` inside ``parameters``.  Promote it to the\n        # constructor argument when the caller did not pass one\n        # explicitly, then strip it from the parameters object so it\n        # never reaches provider-specific request payloads.\n        param_dump = resolved_parameters.model_dump()\n        legacy_dimensions = param_dump.pop(\"dimensions\", None)\n        if dimensions is None:\n            if legacy_dimensions is None:\n                raise ValueError(\n                    \"dimensions is required: pass it explicitly to \"\n                    \"EmbeddingModelBase.__init__ or include it in the \"\n                    \"legacy `parameters` mapping.\",\n                )\n            dimensions = int(legacy_dimensions)\n            resolved_parameters = type(resolved_parameters)(**param_dump)\n        elif legacy_dimensions is not None:\n            # Both routes set it — explicit constructor wins, strip the\n            # legacy mirror so it can't drift.\n            resolved_parameters = type(resolved_parameters)(**param_dump)\n\n        if dimensions <= 0:\n            raise ValueError(\n                f\"dimensions must be a positive integer, got {dimensions}.\",\n            )\n\n        self.credential = credential\n        self.model = model","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/embedding/_embedding_base.py#L140-L176","documentation":"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.","triggerScenarios":"Constructing an embedding model subclass without dimensions=... and without a parameters object containing a dimensions field.","commonSituations":"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.","solutions":["Pass dimensions=1024 (or the model's true dimensionality) to the constructor","Or include dimensions in the legacy parameters mapping if you use that route","Check the provider's docs for the exact dimension count of your chosen model"],"exampleFix":"# before\nmodel = MyDashScopeEmbedding(model=\"text-embedding-v3\", credential=cred)\n# after\nmodel = MyDashScopeEmbedding(model=\"text-embedding-v3\", credential=cred, dimensions=1024)","handlingStrategy":"validation","validationCode":"if dimensions is None:\\n    dimensions = DEFAULT_DIMS[model_name]  # e.g. 1024\nmodel = Emb(model=model_name, dimensions=dimensions, ...)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass dimensions explicitly in model factories","Keep a model->dimensions lookup table next to config"],"tags":["embedding","dimensions","config","init-validation"],"backgroundTag":"missing-required-config","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}