tiangolo/fastapi · error · RuntimeError

Path must be inside {en_docs_path}

Error message

Path must be inside {en_docs_path}

What it means

Raised by add_permalinks_page() in scripts/docs.py:843. The permalink tool only operates on English docs, so it guards with path.is_relative_to(en_docs_path / 'docs') (scripts/docs.py:842). Any path outside docs/en/docs/ is rejected to avoid writing permalinks into translated content or unrelated files.

Source

Thrown at scripts/docs.py:843

        remaining = [
            f
            for f in dir_path.iterdir()
            if f.name != "__pycache__" and f.name != "__init__.py"
        ]
        if not remaining:
            logging.info(f"Removing empty/init-only directory: {dir_path}")
            shutil.rmtree(dir_path)
    print(f"Removed {removed} unused file(s) ✅")


@app.command()
def add_permalinks_page(path: Path, update_existing: bool = False):
    """
    Add or update header permalinks in specific page of En docs.
    """

    if not path.is_relative_to(en_docs_path / "docs"):
        raise RuntimeError(f"Path must be inside {en_docs_path}")
    rel_path = path.relative_to(en_docs_path / "docs")

    # Skip excluded sections
    if str(rel_path).startswith(non_translated_sections):
        return

    visible_text_extractor = VisibleTextExtractor()
    updated_lines = []
    in_code_block3 = False
    in_code_block4 = False
    permalinks = set()

    with path.open("r", encoding="utf-8") as f:
        lines = f.readlines()

    for line in lines:
        # Handle codeblocks start and end
        if not (in_code_block3 or in_code_block4):

View on GitHub (pinned to 3e8d1526d8)

Solutions

1. Pass a path under docs/en/docs/, e.g. docs/en/docs/index.md.
2. If calling from another working directory, resolve the path against the repo root first.
3. For translated docs, run the translation tooling instead — permalinks are propagated via replace_header_permalinks in doc_parsing_utils.py.

Example fix

# before
python scripts/docs.py add-permalinks-page docs/es/docs/index.md
# after
python scripts/docs.py add-permalinks-page docs/en/docs/index.md

from pathlib import Path

def is_en_doc(p: Path) -> bool:
    return p.is_relative_to(Path("docs/en/docs"))

When it happens

Trigger: Invoking the `add-permalinks-page` Typer command (or add_permalinks_page directly) with a Path that does not resolve under docs/en/docs/. Also reachable via add_permalinks / add_permalinks_pages which iterate paths and call this function.

Common situations: Passing a translated docs path (e.g. docs/es/docs/...) by mistake. Passing a relative path resolved from the wrong working directory. Passing a docs_src path or a path under the repo root.

Related errors

• Number of code include placeholders does not match the numbe
• Number of headers with permalinks does not match the number
• Header levels do not match between document and original doc
• Number of markdown links does not match the number in the or
• Number of HTML links does not match the number in the origin

AI-assisted analysis of tiangolo/fastapi@3e8d1526d8 (2026-08-11). Data as JSON: /api/errors/dcbe3ce7ed627024. Report an issue: GitHub.