infiniflow/ragflow · error · GroupValidationError

Only one tree template in a group may enable re-chunking.

Error message

Only one tree template in a group may enable re-chunking.

What it means

Raised by GroupValidationError when saving a compilation template group whose tree templates include more than one with config.raptor.rechunk enabled. The service counts tree-kind templates with raptor.rechunk truthy and rejects the group if that count exceeds one, because re-chunking rebuilds the chunk tree and multiple re-chunking templates in one group would conflict.

Source

Thrown at api/db/services/compilation_template_group_service.py:71

    """At most one tree-kind child in the group may enable re-chunking.

    Re-chunking soft-deletes the doc's original chunks via
    ``available_int=0`` and inserts merged replacements; running two
    such templates would race on the same source chunks and produce
    non-deterministic output. Per-tenant invariant is enforced
    server-side here and mirrored client-side in
    ``group-interface.ts``.
    """
    rechunk_trees = 0
    for t in templates:
        if str((t or {}).get("kind") or "").strip() != "tree":
            continue
        cfg = (t or {}).get("config") or {}
        raptor = (cfg or {}).get("raptor") or {}
        if bool(raptor.get("rechunk")):
            rechunk_trees += 1
    if rechunk_trees > 1:
        raise GroupValidationError("Only one tree template in a group may enable re-chunking.")


class CompilationTemplateGroupService(CommonService):
    model = CompilationTemplateGroup

    @classmethod
    def ensure_table(cls) -> None:
        if not cls.model.table_exists():
            cls.model.create_table(safe=True)

    # ------------------------------------------------------------------
    # Read paths
    # ------------------------------------------------------------------

    @classmethod
    def _group_to_dict(cls, group: CompilationTemplateGroup, templates: list[CompilationTemplate]) -> dict:
        from api.db.services.compilation_template_service import CompilationTemplateService

View on GitHub (pinned to 554fb1133a)

Solutions

1. Set config.raptor.rechunk to false (or remove the key) on all but one tree template in the group before saving.
2. Move the second re-chunking tree template into its own compilation template group.
3. Audit the payload client-side before submit: count kind=='tree' entries with raptor.rechunk truthy and block the request if >1.

Example fix

// before (two tree templates both with):
{"kind": "tree", "config": {"raptor": {"rechunk": true}}}
{"kind": "tree", "config": {"raptor": {"rechunk": true}}}
// after
{"kind": "tree", "config": {"raptor": {"rechunk": true}}}
{"kind": "tree", "config": {"raptor": {"rechunk": false}}}

def count_rechunk_trees(templates):
    n = 0
    for t in templates or []:
        if str((t or {}).get('kind') or '').strip() != 'tree':
            continue
        if bool(((t.get('config') or {}).get('raptor') or {}).get('rechunk')):
            n += 1
    return n

if count_rechunk_trees(payload['templates']) > 1:
    raise ValueError('disable rechunk on all but one tree template')

def is_valid_group_rechunk(templates: list[dict]) -> bool:
    return count_rechunk_trees(templates) <= 1

When it happens

Trigger: PUT/POST of a template group payload where two or more entries have kind=='tree' and config.raptor.rechunk set (e.g. {'raptor': {'rechunk': true}}) in their config objects. The check runs on every create/update of the group.

Common situations: Duplicating an existing re-chunking tree template inside the same group instead of a different group; copying a template's config wholesale when adding a second tree template; frontend defaulting raptor.rechunk to true on new tree templates.

Related errors

• Template {child_id} does not belong to this group.
• Each template must include a name, kind, and config object.
• Template name '{name}' is duplicated in this group.
• Template name '{name}' already exists. Please choose another
• A compilation template named '{name}' already exists. Please

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/44847144fd8f6423. Report an issue: GitHub.