mlflow/mlflow · error · MlflowException

Unable to validate the repository identifier for the Hugging

Error message

Unable to validate the repository identifier for the HuggingFace model hub because the `huggingface-hub` package is not installed. Please install the package with `pip install huggingface-hub` command and retry.

What it means

is_valid_hf_repo_id() validates a string as a HuggingFace repo id using huggingface_hub.utils.validate_repo_id. Because huggingface_hub is an optional dependency, its absence triggers an MlflowException telling the user to pip install huggingface-hub before MLflow can perform the validation.

Source

Thrown at mlflow/utils/huggingface_utils.py:71

        "Unable to fetch model commit hash from the HuggingFace model hub. "
        "This is required for saving a model without base model "
        "weights, while ensuring the version consistency of the model. ",
        error_code=RESOURCE_DOES_NOT_EXIST,
    )


def is_valid_hf_repo_id(maybe_repo_id: str | None) -> bool:
    """
    Check if the given string is a valid HuggingFace repo identifier e.g. "username/repo_id".
    """

    if not maybe_repo_id or os.path.isdir(maybe_repo_id):
        return False

    try:
        from huggingface_hub.utils import HFValidationError, validate_repo_id
    except ImportError:
        raise MlflowException(
            "Unable to validate the repository identifier for the HuggingFace model hub "
            "because the `huggingface-hub` package is not installed. Please install the "
            "package with `pip install huggingface-hub` command and retry."
        )

    try:
        validate_repo_id(maybe_repo_id)
        return True
    except HFValidationError as e:
        _logger.warning(f"The repository identified {maybe_repo_id} is invalid: {e}")
        return False

View on GitHub (pinned to 6a27f2decc)

Solutions

1. Install the package: pip install huggingface-hub (or mlflow[transformers])
2. Add huggingface-hub to your project's requirements/environment definition
3. If you are saving local files instead of a hub repo, pass a local directory path rather than a repo id string so validation is skipped

Example fix

// before
mlflow.huggingface.save_model(model, "my-model")  # MlflowException: huggingface-hub not installed
// after
# pip install huggingface-hub
mlflow.huggingface.save_model(model, "my-model")

try:
    from huggingface_hub.utils import validate_repo_id  # noqa: F401
except ImportError:
    raise SystemExit('Install huggingface-hub to validate/save hub repo ids')

try:
    mlflow.huggingface.save_model(model, repo_id)
except MlflowException as e:
    if 'huggingface-hub' in str(e):
        subprocess.run(['pip', 'install', 'huggingface-hub'], check=True)
        mlflow.huggingface.save_model(model, repo_id)
    else:
        raise

When it happens

Trigger: Calling mlflow.huggingface.save_model (or is_valid_hf_repo_id directly) with a non-empty, non-directory string repo id in an environment where `from huggingface_hub.utils import HFValidationError, validate_repo_id` raises ImportError.

Common situations: Lightweight deployments or skinny MLflow installs without the transformers/huggingface extras; forgot to add huggingface-hub to requirements before pushing to a remote registry sync flow.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• RESOURCE_DOES_NOT_EXIST
• EvaluationDataset is not available. It requires the mlflow.d
• The `databricks-agents` package is required to use `mlflow.g
• The `databricks-agents` package is required to use `mlflow.g
• DSPy library is required but not installed

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