apache/superset · error · ValidationError

Duplicate UUID in folder structure: {uuid}

Error message

Duplicate UUID in folder structure: {uuid}

What it means

Raised by validate_folders() when the same folder uuid appears more than once in the submitted structure. seen_uuids tracks every visited node; a repeat means one folder object was pasted/duplicated or referenced in two places.

Source

Thrown at superset/commands/dataset/update.py:455

    The marshmallow schema will validate the folder structure, but we still need to
    check that UUIDs are valid, names are unique and not reserved, and that there are
    no cycles.
    """
    if not is_feature_enabled("DATASET_FOLDERS"):
        raise ValidationError("Dataset folders are not enabled")

    queue: list[tuple[FolderSchema, list[UUID]]] = [(folder, []) for folder in folders]
    seen_uuids = set()
    seen_fqns = set()  # fully qualified folder names
    while queue:
        obj, path = queue.pop(0)
        uuid, name = obj["uuid"], obj.get("name")

        if uuid in path:
            raise ValidationError(f"Cycle detected: {uuid} appears in its ancestry")

        if uuid in seen_uuids:
            raise ValidationError(f"Duplicate UUID in folder structure: {uuid}")
        seen_uuids.add(uuid)

        # folders can have duplicate name as long as they're not siblings
        if name:
            fqn = tuple(path + [name])
            if name and fqn in seen_fqns:
                raise ValidationError(f"Duplicate folder name: {name}")
            seen_fqns.add(fqn)

            # Allow default folders (by UUID) to use reserved names
            if (
                name.lower() in {"metrics", "columns"}
                and str(uuid) not in DEFAULT_FOLDER_UUIDS
            ):
                raise ValidationError(f"Folder cannot have name '{name}'")

        # check if metric/column UUID exists (skip default folders)
        elif (

View on GitHub (pinned to f4587218dd)

Solutions

1. Find the duplicated uuid named in the message and either remove one occurrence or assign a fresh uuid to the copy.
2. If the same logical folder must appear once, keep a single node — folders are a tree, not a DAG.
3. Dedupe programmatically before submit (see validationCode).

Example fix

# before
[{uuid: U1, children: []}, {uuid: U1, name: "dup", children: []}]
# after
[{uuid: U1, children: []}, {uuid: str(uuid4()), name: "dup", children: []}]

uuids = [f["uuid"] for f in walk(folders)]
assert len(uuids) == len(set(uuids)), f"duplicates: {find_dups(uuids)}"

When it happens

Trigger: PUT /api/v1/dataset/{id} with a folders array containing two nodes sharing a uuid (e.g. the same subfolder attached under two different parents, or a copy-paste duplication).

Common situations: Copy-pasting a folder block in the JSON payload and forgetting to regenerate the uuid. Merging folder trees from two datasets that both contain a shared subfolder id.

Related errors

• Invalid UUID: {uuid}
• Cycle detected: {uuid} appears in its ancestry
• Duplicate folder name: {name}
• Folder cannot have name '{name}'
• Dataset parameters are invalid.

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/b4725bd2b8369b8e. Report an issue: GitHub.