apache/superset · warning · ValidationError

Dataset folders are not enabled

Error message

Dataset folders are not enabled

What it means

ValidationError('Dataset folders are not enabled') is raised by validate_folders() when the payload contains a folder structure but the DATASET_FOLDERS feature flag is off. The folder schema itself may parse, but business validation gates the feature behind is_feature_enabled('DATASET_FOLDERS').

Source

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

            for name, count in Counter([item[key] for item in data]).items()
            if count > 1
        ]
        return duplicates


def validate_folders(  # noqa: C901
    folders: list[FolderSchema],
    valid_uuids: set[UUID],
) -> None:
    """
    Additional folder validation.

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

View on GitHub (pinned to f4587218dd)

Solutions

1. Enable the flag: FEATURE_FLAGS = { ... 'DATASET_FOLDERS': True } in superset_config.py and restart the webserver/workers.
2. Or strip the 'folders' key from the payload if the feature is not wanted.
3. Verify the flag at runtime via /api/v1/feature_flags or superset config dump before sending folder data.

Example fix

# before (superset_config.py)
FEATURE_FLAGS = {"ALERT_REPORTS": True}
PUT /api/v1/dataset/42  body: {"folders": [...]}  # 422 Dataset folders are not enabled

# after
FEATURE_FLAGS = {"ALERT_REPORTS": True, "DATASET_FOLDERS": True}

from superset.utils.feature_flag_manager import is_feature_enabled  # or superset.config check

if "folders" in payload and not is_feature_enabled("DATASET_FOLDERS"):
    payload.pop("folders")  # or abort with a config error

When it happens

Trigger: PUT /api/v1/dataset/{id} (or create) with a 'folders' key in the payload while FEATURE_FLAGS in superset_config.py does not enable DATASET_FOLDERS. Typical when importing/exporting from an instance where the flag was on.

Common situations: Configuration drift: YAML/code imports from a preview environment into production where the flag was never enabled. Upgrading Superset versions where DATASET_FOLDERS ships dark by default. Typo in the feature-flag name in superset_config.py.

Related errors

• Cycle detected: {uuid} appears in its ancestry
• Duplicate UUID in folder structure: {uuid}
• Duplicate folder name: {name}
• Folder cannot have name '{name}'
• Invalid UUID: {uuid}

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