agentscope-ai/agentscope · error · TypeError

The first argument of ApproxTokenChunker must be an ApproxTo

Error message

The first argument of ApproxTokenChunker must be an ApproxTokenChunker.Parameters instance, got {type(parameters).__name__}. Use keyword arguments chunk_size=/overlap= or parameters=Parameters(...).

What it means

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

Source

Thrown at src/agentscope/rag/_chunker/_approx_token_chunker.py:97

                Defaults to ``Parameters()`` when not provided.
            **kwargs (`Any`):
                Deprecated. ``chunk_size`` and ``overlap`` are still
                accepted for backward compatibility and override the
                corresponding fields in ``parameters``; other keys are
                ignored.

        Raises:
            `TypeError`:
                If ``parameters`` is not a ``Parameters`` instance.
            `ValueError`:
                If ``chunk_size`` is not positive, or ``overlap`` is
                negative or not smaller than ``chunk_size``.
        """
        if parameters is not None and not isinstance(
            parameters,
            self.Parameters,
        ):
            raise TypeError(
                "The first argument of ApproxTokenChunker must be an "
                "ApproxTokenChunker.Parameters instance, got "
                f"{type(parameters).__name__}. Use keyword arguments "
                "chunk_size=/overlap= or parameters=Parameters(...).",
            )
        legacy = {
            key: kwargs[key]
            for key in ("chunk_size", "overlap")
            if key in kwargs
        }
        if legacy:
            logger.warning(
                "Passing %s to ApproxTokenChunker directly is deprecated, "
                "use ApproxTokenChunker.Parameters instead.",
                ", ".join(f"``{k}``" for k in legacy),
            )
            base = parameters.model_dump() if parameters is not None else {}
            parameters = self.Parameters(**{**base, **legacy})

View on GitHub (pinned to e90f1c7592)

Solutions

1. Use keyword arguments: ApproxTokenChunker(chunk_size=512, overlap=64)
2. Or build parameters explicitly: Parameters(chunk_size=512, overlap=64) and pass parameters=...
3. Check the migration notes for the chunker API change

Example fix

# before
chunker = ApproxTokenChunker(512, 50)

# after
chunker = ApproxTokenChunker(chunk_size=512, overlap=50)

from agentscope.rag import ApproxTokenChunker

def is_chunker_params(p) -> bool:
    return p is None or isinstance(p, ApproxTokenChunker.Parameters)

When it happens

Trigger: Calling ApproxTokenChunker(512, 50) or ApproxTokenChunker({'chunk_size': 512}) positionally, instead of keyword args or a Parameters object.

Common situations: Upgrading agentscope where the constructor signature changed; following outdated tutorials showing positional chunk_size/overlap.

Related errors

• overlap must be less than chunk_size, got overlap={self.over
• Embedding model returned {len(response.embeddings)} vectors
• The table_format must be one of 'markdown' or 'json', got {t
• Please install pandas to use the Excel parser. You can insta
• Please install pypdf to use the PDF parser. You can install

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