agentscope-ai/agentscope · error · ValueError

Duplicate chunker_type {cls.chunker_type!r}: {seen_chunker_t

Error message

Duplicate chunker_type {cls.chunker_type!r}: {seen_chunker_types[cls.chunker_type].__name__} and {cls.__name__}.

What it means

create_app indexes knowledge chunkers by their chunker_type string; two chunker classes declaring the same chunker_type would overwrite each other in the registry, so configuration raises ValueError naming both conflicting classes.

Source

Thrown at src/agentscope/app/_app.py:342

        chunker_classes = list(
            knowledge_chunkers
            if knowledge_chunkers is not None
            else [ApproxTokenChunker],
        )
        # Backward compatibility: the deprecated ``knowledge_chunker``
        # instance is only used for its class.
        if "knowledge_chunker" in kwargs:
            logger.warning(
                "The `knowledge_chunker` argument of create_app() is "
                "deprecated, use `knowledge_chunkers` instead.",
            )
            legacy_cls = type(kwargs["knowledge_chunker"])
            if legacy_cls not in chunker_classes:
                chunker_classes.append(legacy_cls)
        seen_chunker_types: dict[str, Type[ChunkerBase]] = {}
        for cls in chunker_classes:
            if cls.chunker_type in seen_chunker_types:
                raise ValueError(
                    f"Duplicate chunker_type {cls.chunker_type!r}: "
                    f"{seen_chunker_types[cls.chunker_type].__name__} and "
                    f"{cls.__name__}.",
                )
            seen_chunker_types[cls.chunker_type] = cls
        app.state.knowledge_chunkers = chunker_classes
        app.state.blob_store = (
            blob_store
            if blob_store is not None
            else LocalBlobStore(root_dir="./blobs")
        )
    else:
        app.state.knowledge_parsers = knowledge_parsers
        app.state.knowledge_chunkers = knowledge_chunkers
        app.state.blob_store = blob_store
    app.state.enable_index_worker = (
        enable_index_worker and knowledge_base_manager is not None
    )

View on GitHub (pinned to e90f1c7592)

Solutions

Set a unique chunker_type on your custom chunker class
If subclassing a built-in chunker, override chunker_type with a new name
Remove duplicate chunker classes from the registration list

Example fix

# before
class MyChunker(RecursiveChunker):
    ...  # inherits chunker_type='recursive'

# after
class MyChunker(RecursiveChunker):
    chunker_type = "my_recursive"
    ...

Defensive patterns

Strategy: validation

Validate before calling

def chunker_types_unique(classes) -> bool:
    types = [c.chunker_type for c in classes]
    return len(types) == len(set(types))

Try / catch

try:
    app = create_app(...)
except ValueError as e:
    if "Duplicate chunker_type" in str(e):
        # set unique chunker_type on the named class and retry
        ...

Prevention

Always override chunker_type when subclassing a chunker
Namespace custom chunker types, e.g. 'myorg_recursive'

When it happens

Trigger: Registering two ChunkerBase subclasses (including via the legacy knowledge_chunker kwarg) whose chunker_type class attribute matches, e.g. a custom chunker reusing 'recursive' or another built-in type string.

Common situations: Writing a custom chunker and forgetting to set a unique chunker_type; subclassing a built-in chunker without overriding chunker_type; mixing legacy knowledge_chunker kwarg with a chunker list containing the same class's type.

Related errors

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