oobabooga/textgen · error · ValueError

Invalid branch name. Only alphanumeric characters, period, u

Error message

Invalid branch name. Only alphanumeric characters, period, underscore and dash are allowed.

What it means

Raised by download-model.py when parsing a 'model:branch' string and the branch component fails the regex ^[a-zA-Z0-9._-]+$. The script splits the model identifier on ':' and validates the second part before querying the Hugging Face tree API. It exists to prevent malformed branch names from producing confusing downstream HTTP errors from the HF API.

Source

Thrown at download-model.py:74

        return session

    def sanitize_model_and_branch_names(self, model, branch):
        model = model.removesuffix("/")

        if model.startswith(base + '/'):
            model = model[len(base) + 1:]

        model_parts = model.split(":")
        model = model_parts[0] if len(model_parts) > 0 else model
        branch = model_parts[1] if len(model_parts) > 1 else branch

        if branch is None:
            branch = "main"
        else:
            pattern = re.compile(r"^[a-zA-Z0-9._-]+$")
            if not pattern.match(branch):
                raise ValueError(
                    "Invalid branch name. Only alphanumeric characters, period, underscore and dash are allowed.")

        return model, branch

    def get_download_links_from_huggingface(self, model, branch, text_only=False, specific_file=None, exclude_pattern=None):
        session = self.session
        page = f"/api/models/{model}/tree/{branch}"
        cursor = b""

        links = []
        sha256 = []
        file_sizes = []
        classifications = []
        has_pytorch = False
        has_pt = False
        has_gguf = False
        has_safetensors = False
        is_lora = False

View on GitHub (pinned to ed888c71f2)

Solutions

  1. Use a plain short branch name: 'user/model:main', 'user/model:dev', 'user/model:v1.0-rc1'.
  2. If you meant a PR or full ref, strip it to the short name (refs/heads/main -> main).
  3. Quote the whole argument in the shell so spaces/special characters are not appended: python download-model.py "user/model:my-branch".
  4. Omit the branch entirely (defaults to 'main') when unsure: python download-model.py user/model.

Example fix

# before
python download-model.py meta-llama/Llama-3-8B-Instruct:refs/heads/main

# after
python download-model.py meta-llama/Llama-3-8B-Instruct:main
Defensive patterns

Strategy: validation

Validate before calling

import re

def valid_model_spec(spec: str) -> bool:
    parts = spec.split(":")
    if len(parts) > 2:
        return False
    branch = parts[1] if len(parts) == 2 else None
    if branch is None or re.fullmatch(r"[a-zA-Z0-9._-]+", branch):
        return True
    return False

assert valid_model_spec("org/model:main")
assert not valid_model_spec("org/model:refs/heads/main")

Try / catch

try:
    downloader.normalize_input(spec)
except ValueError as e:
    print(f"Bad model spec {spec!r}: {e}"); sys.exit(2)

Prevention

When it happens

Trigger: Calling download-model.py (or DownloadModel.get_download_links_from_huggingface via its model normalization path) with an identifier like 'org/model:main branch' (space), 'org/model:refs/heads/main' (slash), 'model:' followed by unicode, or any branch containing '/', ':', '+', '~' or whitespace. Also triggered by a model name that itself contains extra ':' segments, e.g. 'a:b:model'.

Common situations: Passing a full git ref ('refs/heads/main' or 'refs/pr/123') instead of the short branch name; copying a URL fragment that includes slashes or spaces; shell quoting mistakes that append stray characters after the branch.

Related errors

AI-assisted analysis of oobabooga/textgen@ed888c71f2 (2026-08-15). Data as JSON: /api/errors/a46d3547c61ad35d. Report an issue: GitHub.