huggingface/open-r1 · error

Revision {training_args.hub_model_revision} already exists.

Error message

Revision {training_args.hub_model_revision} already exists. Use --overwrite_hub_revision to overwrite it.

What it means

check_hub_revision_exists raises ValueError when the target hub_model_revision already exists on the Hub, contains a README.md, and training_args.overwrite_hub_revision is False. This safety check prevents silently clobbering an existing published revision (an existing training run artifact). Users must explicitly opt in to overwrite.

Source

Thrown at src/open_r1/utils/hub.py:83

    logger.info(f"Pushed to {repo_url} revision {training_args.hub_model_revision} successfully!")

    return future


def check_hub_revision_exists(training_args: SFTConfig | GRPOConfig):
    """Checks if a given Hub revision exists."""
    if repo_exists(training_args.hub_model_id):
        if training_args.push_to_hub_revision is True:
            # First check if the revision exists
            revisions = [rev.name for rev in list_repo_refs(training_args.hub_model_id).branches]
            # If the revision exists, we next check it has a README file
            if training_args.hub_model_revision in revisions:
                repo_files = list_repo_files(
                    repo_id=training_args.hub_model_id,
                    revision=training_args.hub_model_revision,
                )
                if "README.md" in repo_files and training_args.overwrite_hub_revision is False:
                    raise ValueError(
                        f"Revision {training_args.hub_model_revision} already exists. "
                        "Use --overwrite_hub_revision to overwrite it."
                    )


def get_param_count_from_repo_id(repo_id: str) -> int:
    """Function to get model param counts from safetensors metadata or find patterns like 42m, 1.5b, 0.5m or products like 8x7b in a repo ID."""
    try:
        metadata = get_safetensors_metadata(repo_id)
        return list(metadata.parameter_count.values())[0]
    except Exception:
        # Pattern to match products (like 8x7b) and single values (like 42m)
        pattern = r"((\d+(\.\d+)?)(x(\d+(\.\d+)?))?)([bm])"
        matches = re.findall(pattern, repo_id.lower())

        param_counts = []
        for full_match, number1, _, _, number2, _, unit in matches:
            if number2:  # If there's a second number, it's a product

View on GitHub (pinned to 1416fa0cf2)

Solutions

1. Add --overwrite_hub_revision to intentionally replace the existing revision
2. Choose a new --hub_model_revision name (e.g. append a date/version suffix)
3. Delete or rename the existing revision on the Hub if it is no longer needed
4. Check existence beforehand with HfApi().list_repo_refs / list_repo_files to pick a free revision

Example fix

// before
python train.py --hub_model_id org/model --hub_model_revision v1  # ValueError
// after
python train.py --hub_model_id org/model --hub_model_revision v1 --overwrite_hub_revision

from huggingface_hub import HfApi

def revision_exists_on_hub(hub_model_id, revision):
    try:
        refs = {r.name for r in HfApi().list_repo_refs(repo_id=hub_model_id).branches}
        return revision in refs
    except Exception:
        return False

try:
    check_hub_revision_exists(training_args)
except ValueError as e:
    if "already exists" in str(e):
        training_args.overwrite_hub_revision = True  # or pick a new revision
        check_hub_revision_exists(training_args)
    else:
        raise

When it happens

Trigger: Re-running a training script with the same --hub_model_revision that was previously pushed, while the revision on the Hub already has a README.md and --overwrite_hub_revision was not passed.

Common situations: Resuming or re-running an experiment with unchanged args, CI re-running a job after a partial failure, shared team hub_model_id where another member already pushed that revision.

Related errors

• Either `dataset_name` or `dataset_mixture` must be provided
• dataset_mixture must be a dictionary with a 'datasets' key.
• 'datasets' must be a list of dataset configurations
• Column names must be consistent across all dataset configura
• Callback {callback_name} not found in CALLBACKS.

AI-assisted analysis of huggingface/open-r1@1416fa0cf2 (2026-08-30). Data as JSON: /api/errors/1e0596e071be4b11. Report an issue: GitHub.