What causes "--name and --tag are mutually exclusive." in mlflow/mlflow?

Choose one selector: drop --tag if you meant to move named resources, or drop --name entries and rely on the tag filter

mlflow/mlflow · warning · RuntimeError

--name and --tag are mutually exclusive.

Error message

--name and --tag are mutually exclusive.

What it means

move_resources selects rows either by explicit --name values or by --tag filters, never both. Supplying both raises a RuntimeError to keep the selection unambiguous.

Source

Thrown at mlflow/store/db/workspace_move.py:291

    Returns a :class:`MoveResult` with ``names`` (sorted list of distinct
    resource names that were moved or would be moved) and ``row_count`` (the
    number of rows in the root resource table that were moved; child-table
    rows such as model versions or tags are not included in this count).
    For resource types whose names are not unique, ``row_count`` may exceed
    ``len(names)`` when multiple rows share the same name.
    """
    if source_workspace == target_workspace:
        raise RuntimeError("Source and target workspaces must be different.")

    spec = _RESOURCE_SPECS.get(resource_type)
    if spec is None:
        raise RuntimeError(
            f"Unknown resource type {resource_type!r}. "
            f"Valid types: {', '.join(RESOURCE_TYPE_CHOICES)}"
        )

    if names and tags:
        raise RuntimeError("--name and --tag are mutually exclusive.")

    if tags and spec.tag_table is None:
        raise RuntimeError(f"Resource type {resource_type!r} does not support tag filtering.")

    if artifact_policy not in ("preserve", "retarget"):
        raise RuntimeError(f"Unknown artifact policy {artifact_policy!r}.")

    if artifact_policy == "retarget" and resource_type != "experiments":
        raise RuntimeError(
            "--artifact-policy retarget is only supported for --resource-type experiments."
        )

    workspace_store.get_workspace(source_workspace)
    workspace_store.get_workspace(target_workspace)

    retarget_root = None
    if artifact_policy == "retarget":
        retarget_root = _resolve_target_artifact_root(

View on GitHub (pinned to 6a27f2decc)

Solutions

Choose one selector: drop --tag if you meant to move named resources, or drop --name entries and rely on the tag filter
Split into two invocations if both name-based and tag-based moves are needed
In scripts, build the command with mutually exclusive flag groups

Example fix

# before: both flags
mlflow workspace move-resources --workspace team-a --resource-type experiments --name exp1 --tag team=x
# after: one selector
mlflow workspace move-resources --workspace team-a --resource-type experiments --tag team=x

Defensive patterns

Strategy: validation

Validate before calling

def validate_selection_args(names, tags):
    if names and tags:
        raise SystemExit('--name and --tag are mutually exclusive; pass one or the other')

validate_selection_args(args.name, args.tag)

Prevention

Use argparse mutually-exclusive flag groups in wrapper scripts
Emit either --name or --tag from automation, never both
Split mixed selections into separate move invocations

When it happens

Trigger: Invoking `mlflow workspace move-resources` with both --name (possibly repeated) and --tag on the same command line.

Common situations: Script merging two selection modes, copying a command template and appending a tag filter on top of explicit names, batch tooling that always emits both flags.

Related errors

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