tiangolo/fastapi · error · ValueError

Code block (lines {start_line}-{end_line_no}) has different

Error message

Code block (lines {start_line}-{end_line_no}) has different language than the original block ('{block_a['lang']}' vs '{block_b['lang']}')

What it means

Raised by `replace_multiline_code_block` (scripts/doc_parsing_utils.py:584) as a ValueError when a fenced code block in the translated document has a different language tag (the token after ```) than the corresponding block in the English original. The pipeline replaces code content while preserving comments from the translation, but only within blocks of the same language; a language mismatch signals the blocks are not equivalent.

Source

Thrown at scripts/doc_parsing_utils.py:584

        return code, comment
    return line, None


def replace_multiline_code_block(
    block_a: MultilineCodeBlockInfo, block_b: MultilineCodeBlockInfo
) -> list[str]:
    """
    Replace multiline code block `a` with block `b` leaving comments intact.

    Syntax of comments depends on the language of the code block.
    Raises ValueError if the blocks are not compatible (different languages or different number of lines).
    """

    start_line = block_a["start_line_no"]
    end_line_no = start_line + len(block_a["content"]) - 1

    if block_a["lang"] != block_b["lang"]:
        raise ValueError(
            f"Code block (lines {start_line}-{end_line_no}) "
            "has different language than the original block "
            f"('{block_a['lang']}' vs '{block_b['lang']}')"
        )
    if len(block_a["content"]) != len(block_b["content"]):
        raise ValueError(
            f"Code block (lines {start_line}-{end_line_no}) "
            "has different number of lines than the original block "
            f"({len(block_a['content'])} vs {len(block_b['content'])})"
        )

    block_language = block_a["lang"].lower()
    if block_language in {"mermaid"}:
        if block_a != block_b:
            print(
                f"Skipping mermaid code block replacement (lines {start_line}-{end_line_no}). "
                "This should be checked manually."
            )

View on GitHub (pinned to 3e8d1526d8)

Solutions

Use the identical language token (e.g. ```python) on the translated block as on the English block.
Keep the same number and order of fenced code blocks so pairing is correct.
Avoid re-tagging blocks; if a different language is genuinely needed, update both source and translation together.

Example fix

// before (English: ```python, translation: ```py)
```py
x = 1
```
// after
```python
x = 1
```

Defensive patterns

Strategy: validation

Validate before calling

from scripts.doc_parsing_utils import extract_multiline_code_blocks

def code_block_langs_match(translated_lines, en_lines) -> bool:
    a = extract_multiline_code_blocks(translated_lines)
    b = extract_multiline_code_blocks(en_lines)
    return len(a) == len(b) and all(x['lang'].lower() == y['lang'].lower() for x, y in zip(a, b))

Type guard

def corresponding_blocks_same_lang(translated_lines, en_lines) -> bool:
    from scripts.doc_parsing_utils import extract_multiline_code_blocks
    a = extract_multiline_code_blocks(translated_lines)
    b = extract_multiline_code_blocks(en_lines)
    return len(a) == len(b) and all(x['lang'].lower() == y['lang'].lower() for x, y in zip(a, b))

Prevention

Copy the exact language token (e.g. python, not py) from the English block.
Keep the same number and order of fenced code blocks in translations.
Do not re-tag code blocks; update source and translation together if a language must change.

When it happens

Trigger: Running the docs translation check where a translator changed ```python to ```py, or ```bash to ```sh, or renamed ```Python (case difference matters since comparison is case-insensitive but the token must still parse). A block re-tagged to ```text or ```json. Blocks out of order so a different block is paired positionally.

Common situations: Inconsistent language aliases (py vs python) between translation and source. Translators 'fixing' the language hint. Adding/removing code blocks so positional pairing aligns the wrong blocks. Case differences are tolerated only after `.lower()`, but token presence still must match.

Related errors

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