{"record":{"id":"618aefc3c2ca0610","repo":"agentscope-ai/agentscope","slug":"the-first-argument-of-approxtokenchunker-must-be-a","errorCode":null,"errorMessage":"The first argument of ApproxTokenChunker must be an ApproxTokenChunker.Parameters instance, got {type(parameters).__name__}. Use keyword arguments chunk_size=/overlap= or parameters=Parameters(...).","messagePattern":"The first argument of ApproxTokenChunker must be an ApproxTokenChunker\\.Parameters instance, got (.+?)\\. Use keyword arguments chunk_size=/overlap= or parameters=Parameters\\(\\.\\.\\.\\)\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/agentscope/rag/_chunker/_approx_token_chunker.py","lineNumber":97,"sourceCode":"                Defaults to ``Parameters()`` when not provided.\n            **kwargs (`Any`):\n                Deprecated. ``chunk_size`` and ``overlap`` are still\n                accepted for backward compatibility and override the\n                corresponding fields in ``parameters``; other keys are\n                ignored.\n\n        Raises:\n            `TypeError`:\n                If ``parameters`` is not a ``Parameters`` instance.\n            `ValueError`:\n                If ``chunk_size`` is not positive, or ``overlap`` is\n                negative or not smaller than ``chunk_size``.\n        \"\"\"\n        if parameters is not None and not isinstance(\n            parameters,\n            self.Parameters,\n        ):\n            raise TypeError(\n                \"The first argument of ApproxTokenChunker must be an \"\n                \"ApproxTokenChunker.Parameters instance, got \"\n                f\"{type(parameters).__name__}. Use keyword arguments \"\n                \"chunk_size=/overlap= or parameters=Parameters(...).\",\n            )\n        legacy = {\n            key: kwargs[key]\n            for key in (\"chunk_size\", \"overlap\")\n            if key in kwargs\n        }\n        if legacy:\n            logger.warning(\n                \"Passing %s to ApproxTokenChunker directly is deprecated, \"\n                \"use ApproxTokenChunker.Parameters instead.\",\n                \", \".join(f\"``{k}``\" for k in legacy),\n            )\n            base = parameters.model_dump() if parameters is not None else {}\n            parameters = self.Parameters(**{**base, **legacy})","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/rag/_chunker/_approx_token_chunker.py#L79-L115","documentation":"ApproxTokenChunker.__init__ reserves its first positional parameter for a Parameters instance. Passing anything else there (an int like 512, a dict) raises TypeError with guidance to use keyword arguments instead — this guards against the old call signature ApproxTokenChunker(512, 50).","triggerScenarios":"Calling ApproxTokenChunker(512, 50) or ApproxTokenChunker({'chunk_size': 512}) positionally, instead of keyword args or a Parameters object.","commonSituations":"Upgrading agentscope where the constructor signature changed; following outdated tutorials showing positional chunk_size/overlap.","solutions":["Use keyword arguments: ApproxTokenChunker(chunk_size=512, overlap=64)","Or build parameters explicitly: Parameters(chunk_size=512, overlap=64) and pass parameters=...","Check the migration notes for the chunker API change"],"exampleFix":"# before\nchunker = ApproxTokenChunker(512, 50)\n\n# after\nchunker = ApproxTokenChunker(chunk_size=512, overlap=50)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"from agentscope.rag import ApproxTokenChunker\n\ndef is_chunker_params(p) -> bool:\n    return p is None or isinstance(p, ApproxTokenChunker.Parameters)","tryCatchPattern":null,"preventionTips":["Always use keyword args chunk_size=/overlap= when constructing the chunker","Check migration notes when upgrading agentscope"],"tags":["agentscope","rag","chunking","api-signature","migration"],"backgroundTag":"breaking-api-signature","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}