mlflow/mlflow · error · MlflowException

INVALID_PARAMETER_VALUE

INVALID_PARAMETER_VALUE

Error message

Invalid deletion mode '{mode}'. Must be one of: {', '.join(m.value for m in WorkspaceDeletionMode)}

What it means

delete_workspace validates the mode argument by constructing the WorkspaceDeletionMode enum; an unrecognized value raises ValueError, which MLflow re-raises as INVALID_PARAMETER_VALUE listing the valid modes. Valid values are SET_DEFAULT, CASCADE, and RESTRICT.

Source

Thrown at mlflow/tracking/_workspace/fluent.py:144

            description=description,
            default_artifact_root=default_artifact_root,
            trace_archival_config=trace_archival_config,
        )
    )


@experimental(version="3.10.0")
def delete_workspace(name: str, *, mode: str = WorkspaceDeletionMode.RESTRICT) -> None:
    """Delete an existing workspace.

    Args:
        name: Name of the workspace to delete.
        mode: Deletion mode. One of SET_DEFAULT, CASCADE, or RESTRICT.
    """
    try:
        deletion_mode = WorkspaceDeletionMode(mode)
    except ValueError:
        raise MlflowException.invalid_parameter_value(
            f"Invalid deletion mode '{mode}'. "
            f"Must be one of: {', '.join(m.value for m in WorkspaceDeletionMode)}"
        )
    if name != DEFAULT_WORKSPACE_NAME:
        WorkspaceNameValidator.validate(name)
    _workspace_client_call(lambda client: client.delete_workspace(name=name, mode=deletion_mode))


__all__ = [
    "Workspace",
    "set_workspace",
    "list_workspaces",
    "get_workspace",
    "create_workspace",
    "update_workspace",
    "delete_workspace",
]

View on GitHub (pinned to 6a27f2decc)

Solutions

Pass one of the exact strings: 'SET_DEFAULT', 'CASCADE', or 'RESTRICT' (case-sensitive).
Import and use the enum: from mlflow.tracking._workspace import WorkspaceDeletionMode; delete_workspace(name, mode=WorkspaceDeletionMode.CASCADE).
Normalize/validate user input to uppercase before passing it.
For RESTRICT, ensure the workspace has no dependent resources, or choose CASCADE to delete them.

Example fix

// before
delete_workspace(name='ws', mode='cascade')  # invalid
// after
from mlflow.tracking._workspace import WorkspaceDeletionMode
delete_workspace(name='ws', mode=WorkspaceDeletionMode.CASCADE)

Defensive patterns

Strategy: validation

Validate before calling

from mlflow.tracking._workspace import WorkspaceDeletionMode

def validate_deletion_mode(mode: str) -> None:
    if isinstance(mode, str):
        mode = mode.upper()
    allowed = {m.value for m in WorkspaceDeletionMode}
    if mode not in allowed:
        raise ValueError(f'mode must be one of {sorted(allowed)}')

Type guard

def is_workspace_deletion_mode(mode: object) -> bool:
    try:
        WorkspaceDeletionMode(mode)
        return True
    except ValueError:
        return False

Try / catch

from mlflow.exceptions import MlflowException
try:
    delete_workspace(name='ws', mode=mode)
except MlflowException as e:
    if e.error_code == 'INVALID_PARAMETER_VALUE':
        logger.error('Bad deletion mode %r; use SET_DEFAULT, CASCADE, or RESTRICT', mode)
    else:
        raise

Prevention

Always pass WorkspaceDeletionMode enum members instead of raw strings
Normalize user input with .upper() before conversion
Document allowed mode values at the CLI/config boundary

When it happens

Trigger: Calling delete_workspace(name, mode='delete') or any string not exactly matching an enum member (case-sensitive, e.g. 'cascade' lowercase).

Common situations: Typos or lowercase variants of mode names; passing None or a user-supplied config value; switching from another tool's deletion vocabulary (e.g. 'force'/'recursive') to MLflow's modes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/b853acf4a1d9c88e. Report an issue: GitHub.