What causes "Syntax errors found in the following files: {files}" in microsoft/autogen?

Re-run the script locally on the changed files: python check_md_code_blocks.py path/to/file.md and read the per-block pyright output it prints before the raise.

microsoft/autogen · error · RuntimeError

Syntax errors found in the following files: {files}

Error message

Syntax errors found in the following files:
{files}

What it means

RuntimeError raised by the check_md_code_blocks CI script after it has run pyright over every Python code block in the given Markdown files. Individual block failures are logged with the file, line number, highlighted code, and pyright output; the final raise lists every file that contained at least one failing block so CI fails with an actionable aggregate.

Source

Thrown at python/check_md_code_blocks.py:75

                # Run pyright on the temporary file using subprocess.run
                import subprocess

                result = subprocess.run(["pyright", temp_file.name], capture_output=True, text=True)
                if result.returncode != 0:
                    logger.info(" " + darkred("FAIL"))
                    highlighted_code = highlight(code_block, PythonLexer(), TerminalFormatter())  # type: ignore
                    output = f"{faint('========================================================')}\n{red('Error')}: Pyright found issues in {teal(markdown_file_path_with_line_no)}:\n{faint('--------------------------------------------------------')}\n{highlighted_code}\n{faint('--------------------------------------------------------')}\n\n{teal('pyright output:')}\n{red(result.stdout)}{faint('========================================================')}\n"
                    logger.info(output)
                    had_errors = True
                else:
                    logger.info(" " + darkgreen("OK"))

        if had_errors:
            files_with_errors.append(markdown_file_path)

    if files_with_errors:
        raise RuntimeError("Syntax errors found in the following files:\n" + "\n".join(files_with_errors))

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Check code blocks in Markdown files for syntax errors.")
    # Argument is a list of markdown files containing glob patterns
    parser.add_argument("markdown_files", nargs="+", help="Markdown files to check.")
    args = parser.parse_args()
    check_code_blocks(args.markdown_files)

View on GitHub (pinned to 027ecf0a37)

Solutions

Re-run the script locally on the changed files: python check_md_code_blocks.py path/to/file.md and read the per-block pyright output it prints before the raise.
Fix the reported snippet exactly where the output points (markdown_file_path_with_line_no) — usually a typo, a stale import, or a renamed API in the example.
If an example intentionally cannot type-check (illustrative pseudo-code), exclude it per the script's supported skip mechanism or make it a plain non-Python code fence.

Example fix

# before (docs snippet)
from autogen import Agent
agent = Agent(nam="x")  # typo -> pyright error -> RuntimeError

# after
from autogen import AssistantAgent
agent = AssistantAgent(name="x")

Defensive patterns

Strategy: try-catch

Validate before calling

# Lint docs snippets before committing
python check_md_code_blocks.py docs/**/*.md README.md
echo "exit=$?" # non-zero means the RuntimeError listed failing files

Try / catch

try:
    check_code_blocks(["README.md", "docs/*.md"])
except RuntimeError as e:
    print(e)  # lists files whose snippets failed pyright
    sys.exit(1)

Prevention

Run the checker locally on every edited markdown file before pushing.
Keep doc snippets importable/valid: use real, current API names only.
Make the docs CI job run this script so failures surface in the PR, not after merge.

When it happens

Trigger: Running python check_md_code_blocks.py <markdown-files...> (typically as a docs CI job) where any embedded Python snippet has a syntax error, an unresolved import, or a type error that pyright flags.

Common situations: Editing documentation examples and forgetting to test them; README snippets referencing symbols that were renamed in the library; CI failing after a dependency bump because example imports no longer type-check; forgetting that snippets share no state across blocks.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/ef7837c26b466209. Report an issue: GitHub.