tiangolo/fastapi · error · ValueError

Number of code include placeholders does not match the numbe

Error message

Number of code include placeholders does not match the number of code includes in the original document ({len(code_include_lines)} vs {len(original_includes)})

What it means

Raised by `replace_placeholders_with_code_includes` (scripts/doc_parsing_utils.py:124) as a ValueError when the count of `<CODE_INCLUDE>` placeholders in a translated document does not equal the count of `{* ... *}` code-include directives in the original English document. This is a structural-consistency check used by the docs translation CI: translated docs must preserve the same number of code-include markers so they can be substituted back from the English source.

Source

Thrown at scripts/doc_parsing_utils.py:124

    return modified_text


def replace_placeholders_with_code_includes(
    text: list[str], original_includes: list[CodeIncludeInfo]
) -> list[str]:
    """
    Replace code includes placeholders with actual code includes from the original (English) document.
    Fail if the number of placeholders does not match the number of original includes.
    """

    code_include_lines = [
        line_no
        for line_no, line in enumerate(text)
        if line.strip() == CODE_INCLUDE_PLACEHOLDER
    ]

    if len(code_include_lines) != len(original_includes):
        raise ValueError(
            "Number of code include placeholders does not match the number of code includes "
            "in the original document "
            f"({len(code_include_lines)} vs {len(original_includes)})"
        )

    modified_text = text.copy()
    for i, line_no in enumerate(code_include_lines):
        modified_text[line_no] = original_includes[i]["line"]

    return modified_text


# Header permalinks
# --------------------------------------------------------------------------------------


def extract_header_permalinks(lines: list[str]) -> list[HeaderPermalinkInfo]:
    """

View on GitHub (pinned to 3e8d1526d8)

Solutions

Restore the exact number of `{* ... *}` code-include lines to match the current English source.
Re-run the translation tooling that injects placeholders from the English doc.
Sync the translation against the latest English document and re-apply the check.

Example fix

// before
# translated doc has 2 code includes, English has 3
{* path/a.py *}
{* path/b.py *}
// after
{* path/a.py *}
{* path/b.py *}
{* path/c.py *}

Defensive patterns

Strategy: validation

Validate before calling

from scripts.doc_parsing_utils import extract_code_includes, CODE_INCLUDE_RE

def code_includes_match(translated_lines, en_lines) -> bool:
    return len(extract_code_includes(translated_lines)) == len(extract_code_includes(en_lines))

Type guard

def translation_has_same_includes(translated_lines, en_lines) -> bool:
    from scripts.doc_parsing_utils import extract_code_includes
    return len(extract_code_includes(translated_lines)) == len(extract_code_includes(en_lines))

Prevention

Do not edit or remove {* ... *} code-include lines when translating.
Re-run the docs translation check locally before pushing.
Sync translations against the latest English docs before translating new sections.

When it happens

Trigger: Running `check_translation` (or the docs CI lint) on a translated markdown file whose translator removed, duplicated, or altered a `{* ... *}` code-include marker. A code include was converted to a real code block or dropped during translation.

Common situations: Translators editing code-include lines instead of leaving them verbatim. Partial translations that skipped code sections. A merge that duplicated or removed an include line. The original English doc gained/lost an include and the translation was not regenerated.

Related errors

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