How to Report Bugs in olmOCR: A Complete Guide to Issue Templates

To report a bug in olmOCR, search existing issues first, then open a new issue using the 🐛 Bug Report template located at .github/ISSUE_TEMPLATE/bug_report.yml, providing a minimal reproducible example and your environment details.

Reporting bugs effectively helps maintainers of the allenai/olmocr repository resolve issues quickly. When you encounter unexpected behavior in olmOCR's PDF processing pipeline, following the structured bug reporting workflow ensures your issue receives attention without unnecessary back-and-forth clarification.

Check for Existing Issues Before Filing

Always search the repository's existing issues before creating a new report. Use the search query is:issue bug to filter for potential duplicates. This step prevents redundant work and helps you discover temporary workarounds or ongoing fixes that may already address your problem.

Submitting a Bug Report Using the Official Template

The olmOCR repository enforces a standardized workflow through GitHub issue templates. Navigate to the Issues tab and click New issue, then select the 🐛 Bug Report template. This form is defined in .github/ISSUE_TEMPLATE/bug_report.yml and guides you through required fields to ensure maintainers receive complete context.

Craft a Clear Title and Description

Summarize the problem in a concise title that indicates the specific failure. In the description body, explain what went wrong, why it impacts your use case, and what behavior you expected instead. Avoid vague statements like "it doesn't work" in favor of specific details like "Running olmocr.pipeline.process() on a PDF with tables crashes with a KeyError."

Provide a Minimal Reproducible Example

Include a short, self-contained code snippet that triggers the bug. The example should import olmOCR, execute the failing operation, and use minimal test data that you can attach or reference via a public URL.

import olmocr

# A tiny PDF that triggers the bug (stored in repo or a public URL)

pdf_path = "tests/data/broken_table.pdf"

# This call raises the error

olmocr.pipeline.process(pdf_path)

Document Your Environment

Paste the output of python --version && pip freeze into the Versions section of the template. This command reveals your exact Python version and all installed package versions, which is critical for reproducing environment-specific bugs.

python --version && pip freeze

Attach Full Tracebacks and Logs

If an exception occurred, copy the complete traceback and wrap it in triple backticks. You may also attach relevant log files such as olmocr-pipeline-debug.log if the pipeline generates debug output during execution.

Key Files Supporting the Bug Reporting Process

The following source files define the bug reporting standards for the repository:

• .github/ISSUE_TEMPLATE/bug_report.yml – The official structured form that appears when you select "Bug Report" in the GitHub issue creation interface.
• .github/CONTRIBUTING.md – General contribution guidelines that outline community standards for filing issues and submitting fixes.
• README.md – Contains references to the issue templates and quick links to reporting documentation.

Summary

• Search existing issues using is:issue bug to avoid duplicates before filing.
• Use the structured bug report template at .github/ISSUE_TEMPLATE/bug_report.yml when creating new issues.
• Provide minimal reproducible code examples that demonstrate the specific failure.
• Include complete environment details by running python --version && pip freeze.
• Attach full error tracebacks and relevant log files to speed up diagnosis.

Frequently Asked Questions

Where is the bug report template located in the olmOCR repository?

The template is defined in .github/ISSUE_TEMPLATE/bug_report.yml in the allenai/olmocr repository. When you click "New issue" on GitHub, this template automatically loads the structured form fields for bug reports.

What information is required when reporting a bug in olmOCR?

You must provide a clear description of the problem, a minimal reproducible code example, the output of python --version && pip freeze to show your environment, and any relevant tracebacks or log files. The template enforces these fields to ensure maintainers have sufficient context.

Should I search existing issues before creating a new bug report for olmOCR?

Yes, always search existing issues using filters like is:issue bug to check for duplicates. This prevents redundant reports and may reveal existing solutions or workarounds for your specific problem.

How should I format code and error logs in my olmOCR bug report?

Wrap all code blocks and error tracebacks in triple backticks () and specify the language when applicable (e.g., python or ```bash). This ensures proper formatting and readability for maintainers reviewing your issue.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}