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

> Learn how to report bugs in olmOCR effectively. Use the bug report template to submit issues with reproducible examples and environment details for faster resolution.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/allenai/olmocr/blob/main/.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`](https://github.com/allenai/olmocr/blob/main/.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.

```python
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.

```bash
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`](https://github.com/allenai/olmocr/blob/main/.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`](https://github.com/allenai/olmocr/blob/main/.github/CONTRIBUTING.md)** – General contribution guidelines that outline community standards for filing issues and submitting fixes.
- **[`README.md`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/.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`](https://github.com/allenai/olmocr/blob/main/.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.