mlflow/mlflow · error · ValueError

Parameter 'name' is only supported in Databricks environment

Error message

Parameter 'name' is only supported in Databricks environments. Use 'dataset_id' parameter instead.

What it means

Outside Databricks, genai dataset APIs identify datasets by dataset_id, not name. _validate_non_databricks_params raises ValueError if a name is supplied to delete_dataset in a non-Databricks environment.

Source

Thrown at mlflow/genai/datasets/__init__.py:107

        )


def _validate_non_databricks_params(
    name: str | None,
    dataset_id: str | None = None,
) -> None:
    """
    Validate parameters for non-Databricks environment (delete_dataset).

    Args:
        name: The dataset name parameter (should not be provided)
        dataset_id: The dataset ID parameter (required)

    Raises:
        ValueError: If dataset_id is missing or name is provided
    """
    if name is not None:
        raise ValueError(
            "Parameter 'name' is only supported in Databricks environments. "
            "Use 'dataset_id' parameter instead."
        )
    if dataset_id is None:
        raise ValueError(
            "Parameter 'dataset_id' is required. "
            "Use search_datasets() to find the dataset ID by name if needed."
        )


def _validate_non_databricks_get_params(
    name: str | None,
    dataset_id: str | None = None,
) -> None:
    if name is not None and dataset_id is not None:
        raise ValueError("Cannot specify both 'name' and 'dataset_id'. Use only one parameter.")
    if name is None and dataset_id is None:
        raise ValueError("Either 'name' or 'dataset_id' must be provided.")

View on GitHub (pinned to 6a27f2decc)

Solutions

Use delete_dataset(dataset_id="...") instead, resolving the ID via search_datasets().
Switch the tracking URI to Databricks if name-based access is intended.
Branch on environment: call the Databricks path when is_databricks_uri(get_tracking_uri()) is true.

Example fix

// before
delete_dataset(name="my_eval_dataset")  # outside Databricks
// after
delete_dataset(dataset_id="abc-123")

Defensive patterns

Strategy: validation

Validate before calling

from mlflow.tracking._tracking_service.utils import is_databricks_uri
from mlflow.tracking import get_tracking_uri
if name is not None and not is_databricks_uri(get_tracking_uri()):
    raise ValueError("use dataset_id= outside Databricks")

Type guard

def non_databricks_safe_args(name: str | None) -> bool:
    from mlflow.tracking._tracking_service.utils import is_databricks_uri
    from mlflow.tracking import get_tracking_uri
    return not (name is not None and not is_databricks_uri(get_tracking_uri()))

Try / catch

try:
    delete_dataset(name=name)
except ValueError as e:
    if "only supported in Databricks" in str(e):
        delete_dataset(dataset_id=lookup_id_by_name(name))
    else:
        raise

Prevention

Resolve names to dataset_ids via search_datasets() before non-Databricks operations.
Guard shared code with environment checks.
Prefer dataset_id in CI/local pipelines.

When it happens

Trigger: Calling delete_dataset(name="...") while the tracking URI is NOT a Databricks URI.

Common situations: Code written for Databricks notebooks reused in local/CI environments against a file:// or http tracking server.

Related errors

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