{"record":{"id":"ef7837c26b466209","repo":"microsoft/autogen","slug":"syntax-errors-found-in-the-following-files-files","errorCode":null,"errorMessage":"Syntax errors found in the following files:\n{files}","messagePattern":"Syntax errors found in the following files:\n(.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/check_md_code_blocks.py","lineNumber":75,"sourceCode":"\n                # Run pyright on the temporary file using subprocess.run\n                import subprocess\n\n                result = subprocess.run([\"pyright\", temp_file.name], capture_output=True, text=True)\n                if result.returncode != 0:\n                    logger.info(\" \" + darkred(\"FAIL\"))\n                    highlighted_code = highlight(code_block, PythonLexer(), TerminalFormatter())  # type: ignore\n                    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\"\n                    logger.info(output)\n                    had_errors = True\n                else:\n                    logger.info(\" \" + darkgreen(\"OK\"))\n\n        if had_errors:\n            files_with_errors.append(markdown_file_path)\n\n    if files_with_errors:\n        raise RuntimeError(\"Syntax errors found in the following files:\\n\" + \"\\n\".join(files_with_errors))\n\nif __name__ == \"__main__\":\n    parser = argparse.ArgumentParser(description=\"Check code blocks in Markdown files for syntax errors.\")\n    # Argument is a list of markdown files containing glob patterns\n    parser.add_argument(\"markdown_files\", nargs=\"+\", help=\"Markdown files to check.\")\n    args = parser.parse_args()\n    check_code_blocks(args.markdown_files)\n","sourceCodeStart":57,"sourceCodeEnd":83,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/check_md_code_blocks.py#L57-L83","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before (docs snippet)\nfrom autogen import Agent\nagent = Agent(nam=\"x\")  # typo -> pyright error -> RuntimeError\n\n# after\nfrom autogen import AssistantAgent\nagent = AssistantAgent(name=\"x\")","handlingStrategy":"try-catch","validationCode":"# Lint docs snippets before committing\npython check_md_code_blocks.py docs/**/*.md README.md\necho \"exit=$?\" # non-zero means the RuntimeError listed failing files","typeGuard":null,"tryCatchPattern":"try:\n    check_code_blocks([\"README.md\", \"docs/*.md\"])\nexcept RuntimeError as e:\n    print(e)  # lists files whose snippets failed pyright\n    sys.exit(1)","preventionTips":["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."],"tags":["python","ci","documentation","pyright"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}