tiangolo/fastapi · error · ValueError

Number of code blocks does not match the number in the origi

Error message

Number of code blocks does not match the number in the original document ({len(code_blocks)} vs {len(original_code_blocks)})

What it means

Raised by replace_multiline_code_blocks_in_text() in scripts/doc_parsing_utils.py:656. It is the top-level guard before pairing translated fenced code blocks with English ones: the two documents must contain the same number of fenced code blocks. extract_multiline_code_blocks() (scripts/doc_parsing_utils.py:482) walks lines tracking triple and quad backtick fences, so this fires when a translation has gained or lost a whole fenced block relative to English.

Source

Thrown at scripts/doc_parsing_utils.py:656

            code_block.append(line_b)

    return code_block


def replace_multiline_code_blocks_in_text(
    text: list[str],
    code_blocks: list[MultilineCodeBlockInfo],
    original_code_blocks: list[MultilineCodeBlockInfo],
) -> list[str]:
    """
    Update each code block in `text` with the corresponding code block from
    `original_code_blocks` with comments taken from `code_blocks`.

    Raises ValueError if the number, language, or shape of code blocks do not match.
    """

    if len(code_blocks) != len(original_code_blocks):
        raise ValueError(
            "Number of code blocks does not match the number in the original document "
            f"({len(code_blocks)} vs {len(original_code_blocks)})"
        )

    modified_text = text.copy()
    for block, original_block in zip(code_blocks, original_code_blocks, strict=True):
        updated_content = replace_multiline_code_block(block, original_block)

        start_line_index = block["start_line_no"] - 1
        for i, updated_line in enumerate(updated_content):
            modified_text[start_line_index + i] = updated_line

    return modified_text


# All checks
# --------------------------------------------------------------------------------------

View on GitHub (pinned to 3e8d1526d8)

Solutions

  1. Compare the fenced code blocks in the translated file against the English source at the same path under docs/en/.
  2. Add the missing fenced block or remove the extra one so the counts match.
  3. Watch for accidental triple-backtick sequences inside inline code or prose that the extractor counts as a real fence.
  4. Re-run the docs translation check to confirm both block count and per-block line counts (error 100) now pass.

Example fix

// before — translation is missing the second example block
```Python
app = FastAPI()
```
// after — restore the missing English block as a stub for translation
```Python
app = FastAPI()
```

```Python
@app.get("/")
def read_root():
    return {"Hello": "World"}
```
Defensive patterns

Strategy: validation

Validate before calling

from scripts.doc_parsing_utils import extract_multiline_code_blocks

def block_counts_match(en_lines: list[str], translated_lines: list[str]) -> bool:
    return len(extract_multiline_code_blocks(en_lines)) == len(
        extract_multiline_code_blocks(translated_lines)
    )

Try / catch

try:
    check_translation(doc_lines, en_doc_lines, lang_code, auto_fix=False, path=path)
except ValueError as e:
    if "Number of code blocks" in str(e):
        logging.error(f"Translation {path} has a different code-block count than English")
        raise

Prevention

When it happens

Trigger: check_translation() calls replace_multiline_code_blocks_in_text(doc_lines, doc_code_blocks, en_code_blocks). Fires when len(doc_code_blocks) != len(en_code_blocks) — e.g. the translation has 5 fenced blocks but the English original has 6.

Common situations: A translator deleted a fenced example, duplicated one, or accidentally merged two blocks by removing a fence. The English doc added a new code example and the translation has not been updated. A stray ``` inside prose (e.g. inline `code` mistakenly fenced) opened/closed a phantom block.

Related errors

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