huggingface/transformers · error · ValueError

Could not find TOC entry for {old_lowercase_name}

Error message

Could not find TOC entry for {old_lowercase_name}

What it means

The add_new_model_like CLI copies the documentation TOC entry of the base model to register the new model. It searches docs/source/en/_toctree.yml for a line matching `- local: model_doc/{old_lowercase_name}` followed by a title line. If that regex does not match, it raises ValueError because the new model's docs entry cannot be inserted.

Source

Thrown at src/transformers/cli/add_new_model_like.py:338

):
    """
    Insert the new model in the doc `_toctree.yaml`, in the same section as the old model.

    Args:
        old_lowercase_name (`str`):
            The old lowercase model name.
        new_lowercase_name (`str`):
            The new lowercase model name.
        new_model_paper_name (`str`):
            The fully cased name (as in the official paper name) of the new model.
    """
    toc_file = repo_path / "docs" / "source" / "en" / "_toctree.yml"
    with open(toc_file, "r") as f:
        content = f.read()

    toc_match = re.search(rf"- local: model_doc/{old_lowercase_name}\n {{8}}title: .*?\n", content)
    if toc_match is None:
        raise ValueError(f"Could not find TOC entry for {old_lowercase_name}")
    old_model_toc = toc_match.group(0)
    new_toc = f"      - local: model_doc/{new_lowercase_name}\n        title: {new_model_paper_name}\n"
    add_content_to_file(
        repo_path / "docs" / "source" / "en" / "_toctree.yml", new_content=new_toc, add_after=old_model_toc
    )


def create_init_file(old_lowercase_name: str, new_lowercase_name: str, filenames_to_add: list[tuple[str, bool]]):
    """
    Create the `__init__.py` file to add in the new model folder.

    Args:
        old_lowercase_name (`str`):
            The old lowercase model name.
        new_lowercase_name (`str`):
            The new lowercase model name.
        filenames_to_add (`list[tuple[str, bool]]`):
            A list of tuples of all potential filenames to add for a new model, along a boolean flag describing if we

View on GitHub (pinned to a597f97485)

Solutions

1. Pick a base model that has its own model_doc/<name> entry in docs/source/en/_toctree.yml
2. Manually add a `- local: model_doc/{old_name}` entry (with 8-space-indented `title:` line) to _toctree.yml and re-run
3. Add the new model's TOC entry by hand and skip the automated step

Example fix

# before: base model 'tiny_bert' has no model_doc page
# after: add to docs/source/en/_toctree.yml
      - local: model_doc/tiny_bert
        title: Tiny BERT

import re
from pathlib import Path

content = (Path("docs/source/en/_toctree.yml")).read_text()
if not re.search(rf"- local: model_doc/{old_name}\n {{8}}title: .*?\n", content):
    print(f"No TOC entry for {old_name}; add it or pick another base model")

When it happens

Trigger: Running add-new-model-like where the old model has no model_doc page (e.g. a model type whose docs are merged into another page); the _toctree.yml formatting changed (different indentation than 8 spaces or a reordered title line); the old name contains characters that were normalized differently than the doc entry.

Common situations: Using a base model whose documentation is embedded in a parent page; running the command on a repo checkout where docs were reorganized; regex breakage after a docs tooling refactor changes indentation in _toctree.yml.

Related errors

• {lowercase_name} is not a valid model name
• You need to install `libcst` to run this command -> `pip ins
• {x} is not a value that can be converted to a bool.
• The server running on {url} returned status code {output.sta
• Failed to convert `generate_flags` into a valid JSON object.

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/276ce7350635122f. Report an issue: GitHub.