apache/superset · error · ValidationError

Folder cannot have name '{name}'

Error message

Folder cannot have name '{name}'

What it means

Raised by validate_folders() when a named (user-created) folder uses the reserved names 'metrics' or 'columns' in any casing. Only default folders — identified by the fixed uuids in DEFAULT_FOLDER_UUIDS — may carry those names, because they anchor the built-in pseudo-folders for metrics and columns.

Source

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

            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 (
            not name
            and uuid not in valid_uuids
            and str(uuid) not in DEFAULT_FOLDER_UUIDS
        ):
            raise ValidationError(f"Invalid UUID: {uuid}")

        # traverse children
        if children := obj.get("children"):
            path.append(uuid)
            queue.extend((folder, path) for folder in children)

View on GitHub (pinned to f4587218dd)

Solutions

1. Rename the folder to something else ('My metrics', 'KPIs'), keeping the reserved words for the built-in folders.
2. If you intended to move items into the default metrics/columns folders, reference the default folder by its DEFAULT_FOLDER_UUIDS uuid instead of creating a new named node.
3. Check casing — the guard lowercases the name, so 'Metrics' is equally rejected.

Example fix

# before
{"uuid": "<random>", "name": "Metrics", "children": []}
# after
{"uuid": "<random>", "name": "My metrics", "children": []}

RESERVED = {"metrics", "columns"}
DEFAULT_FOLDER_UUIDS = {...}  # from superset.constants / update module

for node in walk(folders):
    name = (node.get("name") or "").lower()
    if name in RESERVED and str(node["uuid"]) not in DEFAULT_FOLDER_UUIDS:
        node["name"] += " (custom)"

When it happens

Trigger: PUT /api/v1/dataset/{id} with a folders entry having name 'Metrics' or 'COLUMNS' (case-insensitive) whose uuid is not one of the default-folder uuids.

Common situations: Users organizing custom folders try to name one 'Metrics' for their computed metrics, colliding with the reserved default. Imported folder trees that copied the default names without the default uuids.

Related errors

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

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